kumquat-buildroot/docs/manual/adding-packages-asciidoc.txt
Yann E. MORIN 6a6a11f64b package/doc-asciidoc: allow docs to request a specific TOC depth
For some documents, we may want a terse or deeper TOC depth. For
example, short documents may want just the level-0 in the TOC, while
longer documents may want depth 1 or 2, or even deeper; also, some
documents may not use the document-title levels [0], only section
levels [1], and so may want to increase the TOC depth.

Additionally, allow per-format depth. For example, split-html has a
single page dedicated to the TOC, so there we may want a deeper TOC,
while on the html output, where the TOC is on the same page as the
whole document, a shorter TOC is preferred.

[0] https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#document-header
[1] https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#section-titles

Signed-off-by: Yann E. MORIN <yann.morin@orange.com>
Signed-off-by: Arnout Vandecappelle <arnout@mind.be>
2023-04-10 21:49:22 +02:00

144 lines
5.2 KiB
Plaintext

// -*- mode:doc; -*-
// vim: syntax=asciidoc
=== Infrastructure for asciidoc documents
[[asciidoc-documents-tutorial]]
The Buildroot manual, which you are currently reading, is entirely written
using the http://asciidoc.org/[AsciiDoc] mark-up syntax. The manual is then
rendered to many formats:
* html
* split-html
* pdf
* epub
* text
Although Buildroot only contains one document written in AsciiDoc, there
is, as for packages, an infrastructure for rendering documents using the
AsciiDoc syntax.
Also as for packages, the AsciiDoc infrastructure is available from a
xref:outside-br-custom[br2-external tree]. This allows documentation for
a br2-external tree to match the Buildroot documentation, as it will be
rendered to the same formats and use the same layout and theme.
==== +asciidoc-document+ tutorial
Whereas package infrastructures are suffixed with +-package+, the document
infrastructures are suffixed with +-document+. So, the AsciiDoc infrastructure
is named +asciidoc-document+.
Here is an example to render a simple AsciiDoc document.
----
01: ################################################################################
02: #
03: # foo-document
04: #
05: ################################################################################
06:
07: FOO_SOURCES = $(sort $(wildcard $(FOO_DOCDIR)/*))
08: $(eval $(call asciidoc-document))
----
On line 7, the Makefile declares what the sources of the document are.
Currently, it is expected that the document's sources are only local;
Buildroot will not attempt to download anything to render a document.
Thus, you must indicate where the sources are. Usually, the string
above is sufficient for a document with no sub-directory structure.
On line 8, we call the +asciidoc-document+ function, which generates all
the Makefile code necessary to render the document.
==== +asciidoc-document+ reference
The list of variables that can be set in a +.mk+ file to give metadata
information is (assuming the document name is +foo+) :
* +FOO_SOURCES+, mandatory, defines the source files for the document.
* +FOO_RESOURCES+, optional, may contain a space-separated list of paths
to one or more directories containing so-called resources (like CSS or
images). By default, empty.
* +FOO_DEPENDENCIES+, optional, the list of packages (most probably,
host-packages) that must be built before building this document.
* +FOO_TOC_DEPTH+, +FOO_TOC_DEPTH_<FMT>+, optionals, the depth of the
table of content for this document, which can be overridden for the
specified format +<FMT>+ (see the list of rendered formats, above,
but in uppercase, and with dash replaced by underscore; see example,
below). By default: +1+.
There are also additional hooks (see xref:hooks[] for general information
on hooks), that a document may set to define extra actions to be done at
various steps:
* +FOO_POST_RSYNC_HOOKS+ to run additional commands after the sources
have been copied by Buildroot. This can for example be used to
generate part of the manual with information extracted from the
tree. As an example, Buildroot uses this hook to generate the tables
in the appendices.
* +FOO_CHECK_DEPENDENCIES_HOOKS+ to run additional tests on required
components to generate the document. In AsciiDoc, it is possible to
call filters, that is, programs that will parse an AsciiDoc block and
render it appropriately (e.g. http://ditaa.sourceforge.net/[ditaa] or
https://pythonhosted.org/aafigure/[aafigure]).
* +FOO_CHECK_DEPENDENCIES_<FMT>_HOOKS+, to run additional tests for
the specified format +<FMT>+ (see the list of rendered formats, above).
Buildroot sets the following variable that can be used in the definitions
above:
* +$(FOO_DOCDIR)+, similar to +$(FOO_PKGDIR)+, contains the path to the
directory containing +foo.mk+. It can be used to refer to the document
sources, and can be used in the hooks, especially the post-rsync hook
if parts of the documentation needs to be generated.
* +$(@D)+, as for traditional packages, contains the path to the directory
where the document will be copied and built.
Here is a complete example that uses all variables and all hooks:
----
01: ################################################################################
02: #
03: # foo-document
04: #
05: ################################################################################
06:
07: FOO_SOURCES = $(sort $(wildcard $(FOO_DOCDIR)/*))
08: FOO_RESOURCES = $(sort $(wildcard $(FOO_DOCDIR)/ressources))
09:
10: FOO_TOC_DEPTH = 2
11: FOO_TOC_DEPTH_HTML = 1
12: FOO_TOC_DEPTH_SPLIT_HTML = 3
13:
14: define FOO_GEN_EXTRA_DOC
15: /path/to/generate-script --outdir=$(@D)
16: endef
17: FOO_POST_RSYNC_HOOKS += FOO_GEN_EXTRA_DOC
18:
19: define FOO_CHECK_MY_PROG
20: if ! which my-prog >/dev/null 2>&1; then \
21: echo "You need my-prog to generate the foo document"; \
22: exit 1; \
23: fi
24: endef
25: FOO_CHECK_DEPENDENCIES_HOOKS += FOO_CHECK_MY_PROG
26:
27: define FOO_CHECK_MY_OTHER_PROG
28: if ! which my-other-prog >/dev/null 2>&1; then \
29: echo "You need my-other-prog to generate the foo document as PDF"; \
30: exit 1; \
31: fi
32: endef
33: FOO_CHECK_DEPENDENCIES_PDF_HOOKS += FOO_CHECK_MY_OTHER_PROG
34:
35: $(eval $(call asciidoc-document))
----