docs/manual/adding-packages-asciidoc.txt

   1 // -*- mode:doc; -*-
   2 // vim: syntax=asciidoc
   3
   4 === Infrastructure for asciidoc documents
   5
   6 [[asciidoc-documents-tutorial]]
   7
   8 The Buildroot manual, which you are currently reading, is entirely written
   9 using the http://asciidoc.org/[AsciiDoc] mark-up syntax. The manual is then
  10 rendered to many formats:
  11
  12 * html
  13 * split-html
  14 * pdf
  15 * epub
  16 * text
  17
  18 Although Buildroot only contains one document written in AsciiDoc, there
  19 is, as for packages, an infrastructure for rendering documents using the
  20 AsciiDoc syntax.
  21
  22 Also as for packages, the AsciiDoc infrastructure is available from a
  23 xref:outside-br-custom[br2-external tree]. This allows documentation for
  24 a br2-external tree to match the Buildroot documentation, as it will be
  25 rendered to the same formats and use the same layout and theme.
  26
  27 ==== +asciidoc-document+ tutorial
  28
  29 Whereas package infrastructures are suffixed with +-package+, the document
  30 infrastructures are suffixed with +-document+. So, the AsciiDoc infrastructure
  31 is named +asciidoc-document+.
  32
  33 Here is an example to render a simple AsciiDoc document.
  34
  35 ----
  36 01: ################################################################################
  37 02: #
  38 03: # foo-document
  39 04: #
  40 05: ################################################################################
  41 06:
  42 07: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*))
  43 08: $(eval $(call asciidoc-document))
  44 ----
  45
  46 On line 7, the Makefile declares what the sources of the document are.
  47 Currently, it is expected that the document's sources are only local;
  48 Buildroot will not attempt to download anything to render a document.
  49 Thus, you must indicate where the sources are. Usually, the string
  50 above is sufficient for a document with no sub-directory structure.
  51
  52 On line 8, we call the +asciidoc-document+ function, which generates all
  53 the Makefile code necessary to render the document.
  54
  55 ==== +asciidoc-document+ reference
  56
  57 The list of variables that can be set in a +.mk+ file to give metadata
  58 information is (assuming the document name is +foo+) :
  59
  60 * +FOO_SOURCES+, mandatory, defines the source files for the document.
  61
  62 * +FOO_RESOURCES+, optional, may contain a space-separated list of paths
  63   to one or more directories containing so-called resources (like CSS or
  64   images). By default, empty.
  65
  66 * +FOO_DEPENDENCIES+, optional, the list of packages (most probably,
  67   host-packages) that must be built before building this document.
  68   If a hook of your document needs to access the _Kconfig_ structure,
  69   you may add +prepare-kconfig+ to the list of dependencies.
  70
  71 There are also additional hooks (see xref:hooks[] for general information
  72 on hooks), that a document may set to define extra actions to be done at
  73 various steps:
  74
  75 * +FOO_POST_RSYNC_HOOKS+ to run additional commands after the sources
  76   have been copied by Buildroot. This can for example be used to
  77   generate part of the manual with information extracted from the
  78   tree. As an example, Buildroot uses this hook to generate the tables
  79   in the appendices.
  80
  81 * +FOO_CHECK_DEPENDENCIES_HOOKS+ to run additional tests on required
  82   components to generate the document. In AsciiDoc, it is possible to
  83   call filters, that is, programs that will parse an AsciiDoc block and
  84   render it appropriately (e.g. http://ditaa.sourceforge.net/[ditaa] or
  85   https://pythonhosted.org/aafigure/[aafigure]).
  86
  87 * +FOO_CHECK_DEPENDENCIES_<FMT>_HOOKS+, to run additional tests for
  88   the specified format +<FMT>+ (see the list of rendered formats, above).
  89
  90 Here is a complete example that uses all variables and all hooks:
  91
  92 ----
  93 01: ################################################################################
  94 02: #
  95 03: # foo-document
  96 04: #
  97 05: ################################################################################
  98 06:
  99 07: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*))
 100 08: FOO_RESOURCES = $(sort $(wildcard $(pkgdir)/ressources))
 101 09:
 102 10: define FOO_GEN_EXTRA_DOC
 103 11:     /path/to/generate-script --outdir=$(@D)
 104 12: endef
 105 13: FOO_POST_RSYNC_HOOKS += FOO_GEN_EXTRA_DOC
 106 14:
 107 15: define FOO_CHECK_MY_PROG
 108 16:     if ! which my-prog >/dev/null 2>&1; then \
 109 17:         echo "You need my-prog to generate the foo document"; \
 110 18:         exit 1; \
 111 19:     fi
 112 20: endef
 113 21: FOO_CHECK_DEPENDENCIES_HOOKS += FOO_CHECK_MY_PROG
 114 22:
 115 23: define FOO_CHECK_MY_OTHER_PROG
 116 24:     if ! which my-other-prog >/dev/null 2>&1; then \
 117 25:         echo "You need my-other-prog to generate the foo document as PDF"; \
 118 26:         exit 1; \
 119 27:     fi
 120 28: endef
 121 29: FOO_CHECK_DEPENDENCIES_PDF_HOOKS += FOO_CHECK_MY_OTHER_PROG
 122 30:
 123 31: $(eval $(call asciidoc-document))
 124 ----