From 9d140b7db716fdf8e584b31518866de0d6d11dea Mon Sep 17 00:00:00 2001 From: Filip Filmar Date: Tue, 18 Feb 2025 22:13:26 -0800 Subject: [PATCH] doc: adds examples into the documentation --- BUILD.bazel | 8 ++++ doc/01-introduction.md | 41 ++++++++++++++++--- ebook-example/include-files/file1.md | 11 ----- .../include-files/BUILD.bazel | 6 ++- tests/include-files/file1.md | 11 +++++ .../include-files/file2.md | 0 6 files changed, 58 insertions(+), 19 deletions(-) delete mode 100644 ebook-example/include-files/file1.md rename {ebook-example => tests}/include-files/BUILD.bazel (75%) create mode 100644 tests/include-files/file1.md rename {ebook-example => tests}/include-files/file2.md (100%) diff --git a/BUILD.bazel b/BUILD.bazel index 91a6ea9..237428e 100644 --- a/BUILD.bazel +++ b/BUILD.bazel @@ -15,6 +15,14 @@ markdown_lib( "empty.md", # This shouldn't be happening. "//doc:md", "README.md", + "//tests:plantuml_lib_test", + "//tests:md", + "//tests:dot_png_test", + "//tests:drawtiming_lib_test", + "//tests/include-files:md", + ], + additional_inputs = [ + "//tests/include-files:md2", ], ) diff --git a/doc/01-introduction.md b/doc/01-introduction.md index 9c85db1..18f9dcf 100644 --- a/doc/01-introduction.md +++ b/doc/01-introduction.md @@ -1,13 +1,17 @@ # Introduction -This document explains the [bazel-ebook][be] repository and its functionality. -Bazel ebook is a set of tools you can use to publish electronic books of +This document explains the [bazel-ebook][be] source code repository on Github +and its functionality. + +bazel-ebook is a set of tools you can use to publish electronic books of moderate complexity. It relies on existing [pandoc][pdc], which is a universal document format converter. bazel-ebook uses pandoc for most of its heavy lifting. The contribution of bazel-ebook is in automatic installation of all needed -dependencies and the unification of the ebook build process. +dependencies and the unification of the ebook build process. This is useful for +documenting large code bases and pieces of software, especially those that use +[bazel][bzl] as their build system. Using the tools provided in bazel-ebook, you can produce quality documentation for say a piece of software, or a publishable ebook, in any of the following formats: @@ -18,14 +22,39 @@ say a piece of software, or a publishable ebook, in any of the following formats * MOBI (the Amazon Kindle format) * EPUB (the open ebook format) -In proof of this claim, you can find this document +In proof of this claim, you can find this document in one of the serveral formats +at the links below. * [HTML][xht] * [PDF][xpd] -[xht]: https://hdlfactory.com/bazel_ebook_html -[xpd]: https://hdlfactory.com/bazel_ebook_pdf/bazel_ebook_pdf.pdf +## Why? + +Pedantically, each step of the publication flow offered by bazel-ebook is already +covered by some piece of software. Why, then, go through the trouble of providing +yet another way of achieving essentially the same thing? +* Most such software is not amenable to automation. I wanted something that would + be able to automate the entire workflow from start to finish. +* LaTeX exists, but is primarily geared towards printed publication, which is a + bar I did not need to meet. It is also quite involved to weave into modern + build workflows, and even more involved to have it generate publication quality + HTML documentation. +* EPUB can be produced by many pieces of software, not the least of which is + [Google Docs][gdcs]. But, again, keeping your publication in sync with especially + software artifacts is then a completely manual process. I wanted something + fully automated. +* A bazel-based downflow weaves well into other work I do with bazel. I usually + deal with very heterogeneous builds, where having partial build solutions leads + to confusing, redundant, and many times incorrect results. Bazel can take in + all of these processes and order them in a way that produces fast and correct + full or incremental builds. This is something I highly value. + + +[xht]: https://hdlfactory.com/bazel_ebook_html +[xpd]: https://hdlfactory.com/bazel_ebook_pdf/bazel_ebook_pdf.pdf [pdc]: https://pandoc.org [be]: https://github.com/filmil/bazel-ebook +[bzl]: https://bazel.build +[gdcs]: https://docs.google.com diff --git a/ebook-example/include-files/file1.md b/ebook-example/include-files/file1.md deleted file mode 100644 index 4d8e7f9..0000000 --- a/ebook-example/include-files/file1.md +++ /dev/null @@ -1,11 +0,0 @@ -Include once: - -``` {.include} -include-files/file2.md -``` - -Include as code: - -```{include=include-files/file2.md} -``` - diff --git a/ebook-example/include-files/BUILD.bazel b/tests/include-files/BUILD.bazel similarity index 75% rename from ebook-example/include-files/BUILD.bazel rename to tests/include-files/BUILD.bazel index 01b2a19..bcb9829 100644 --- a/ebook-example/include-files/BUILD.bazel +++ b/tests/include-files/BUILD.bazel @@ -1,8 +1,10 @@ -load("@bazel_ebook//build:rules.bzl", +load("//build:rules.bzl", "markdown_lib", "pandoc_standalone_html", ) +package(default_visibility = [ "//visibility:public" ]) + markdown_lib( name = "md", srcs = [ @@ -28,7 +30,7 @@ pandoc_standalone_html( ], title = "Bazel Ebook Tools", filters = [ - "@bazel_ebook//third_party/pandoc-include-code:filter", + "//third_party/pandoc-include-code:filter", "@pandoc_crossref//:pandoc_crossref", ], ) diff --git a/tests/include-files/file1.md b/tests/include-files/file1.md new file mode 100644 index 0000000..77c6208 --- /dev/null +++ b/tests/include-files/file1.md @@ -0,0 +1,11 @@ +Include once: + +``` {.include} +tests/include-files/file2.md +``` + +Include as code: + +```{include=tests/include-files/file2.md} +``` + diff --git a/ebook-example/include-files/file2.md b/tests/include-files/file2.md similarity index 100% rename from ebook-example/include-files/file2.md rename to tests/include-files/file2.md