third_party/pigweed/repo/pw_docgen/docs.rst

   1 .. _module-pw_docgen:
   2
   3 ---------
   4 pw_docgen
   5 ---------
   6 The docgen module provides tools to generate documentation for Pigweed-based
   7 projects, and for Pigweed itself.
   8
   9 Pigweed-based projects typically use a subset of Pigweed's modules and add their
  10 own product-specific modules on top of that, which may have product-specific
  11 documentation. Docgen provides a convenient way to combine all of the relevant
  12 documentation for a project into one place, allowing downstream consumers of
  13 release bundles (e.g. factory teams, QA teams, beta testers, etc.) to have a
  14 unified source of documentation early on.
  15
  16 The documentation generation is integrated directly into the build system. Any
  17 build target can depend on documentation, which allows it to be included as part
  18 of a factory release build, for example. Additionally, documentation itself can
  19 depend on other build targets, such as report cards for binary size/profiling.
  20 Any time the code is changed, documentation will be regenerated with the updated
  21 reports.
  22
  23 Documentation overview
  24 ======================
  25 Each Pigweed module provides documentation describing its functionality, use
  26 cases, and programming API.
  27
  28 Included in a module's documentation are report cards which show an overview of
  29 the module's size cost and performance benchmarks. These allow prospective users
  30 to evaluate the impact of including the module in their projects.
  31
  32 Build integration
  33 =================
  34
  35 Pigweed documentation files are written in `reStructuredText`_ format and
  36 rendered to HTML using `Sphinx`_ through Pigweed's GN build system.
  37
  38 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
  39 .. _Sphinx: http://www.sphinx-doc.org/en/master
  40
  41 Documentation source and asset files are placed alongside code within a module
  42 and registered as a ``pw_docgen_group`` target within a ``BUILD.gn`` file. These
  43 groups become available for import within a special documentation generation
  44 target, which accumulates all of them and renders the resulting HTML. This
  45 system can either be used directly within Pigweed, or integrated into a
  46 downstream project.
  47
  48 GN templates
  49 ------------
  50
  51 pw_doc_group
  52 ____________
  53
  54 The main template for defining documentation files is ``pw_doc_group``. It is
  55 used to logically group a collection of documentation source files and assets.
  56 Each Pigweed module is expected to provide at least one ``pw_doc_group`` target
  57 defining the module's documentation. A ``pw_doc_group`` can depend on other
  58 groups, causing them to be built with it.
  59
  60 **Arguments**
  61
  62 * ``sources``: RST documentation source files.
  63 * ``inputs``: Additional resources required for the docs (images, data files,
  64   etc.)
  65 * ``group_deps``: Other ``pw_doc_group`` targets required by this one.
  66 * ``report_deps``: Report card generating targets (e.g. ``pw_size_report``) on
  67   which the docs depend.
  68
  69 **Example**
  70
  71 .. code::
  72
  73   pw_doc_group("my_doc_group") {
  74     sources = [ "docs.rst" ]
  75     inputs = [ "face-with-tears-of-joy-emoji.svg" ]
  76     group_deps = [ ":sub_doc_group" ]
  77     report_deps = [ ":my_size_report" ]
  78   }
  79
  80 pw_doc_gen
  81 __________
  82
  83 The ``pw_doc_gen`` template creates a target which renders complete HTML
  84 documentation for a project. It depends on registered ``pw_doc_group`` targets
  85 and creates an action which collects and renders them.
  86
  87 To generate the complete docs, the template also requires a ``conf.py`` file
  88 configuring Sphinx's output, and a top level ``index.rst`` for the main page of
  89 the documentation. These are added at the root level of the built documentation
  90 to tie everything together.
  91
  92 **Arguments**
  93
  94 * ``conf``: Path to the ``conf.py`` to use for Sphinx.
  95 * ``index``: Path to the top-level ``index.rst`` file.
  96 * ``output_directory``: Directory in which to render HTML output.
  97 * ``deps``: List of all ``pw_doc_group`` targets required for the documentation.
  98
  99 **Example**
 100
 101 .. code::
 102
 103   pw_doc_gen("my_docs") {
 104     conf = "//my_docs/conf.py"
 105     index = "//my_docs/index.rst"
 106     output_directory = target_gen_dir
 107     deps = [
 108       "//my_module:my_doc_group",
 109     ]
 110   }
 111
 112 Generating documentation
 113 ------------------------
 114
 115 All source files listed under a ``pw_doc_gen`` target and its ``pw_doc_group``
 116 dependencies get copied out into a directory structure mirroring the original
 117 layout of the modules in which the sources appear. This is demonstrated below
 118 using a subset of Pigweed's core documentation.
 119
 120 Consider the following target in ``$dir_pigweed/docs/BUILD.gn``:
 121
 122 .. code::
 123
 124   pw_doc_gen("docs") {
 125     conf = "conf.py"
 126     index = "index.rst"
 127     output_directory = target_gen_dir
 128     deps = [
 129       "$dir_pw_bloat:docs",
 130       "$dir_pw_docgen:docs",
 131       "$dir_pw_preprocessor:docs",
 132     ]
 133   }
 134
 135 A documentation tree is created under the output directory. Each of the sources
 136 and inputs in the target's dependency graph is copied under this tree in the
 137 same directory structure as they appear under the root GN build directory
 138 (``$dir_pigweed`` in this case). The ``conf.py`` and ``index.rst`` provided
 139 directly to the ``pw_doc_gen`` template are copied in at the root of the tree.
 140
 141 .. code::
 142
 143   out/gen/docs/pw_docgen_tree/
 144   ├── conf.py
 145   ├── index.rst
 146   ├── pw_bloat
 147   │   ├── bloat.rst
 148   │   └── examples
 149   │       └── simple_bloat.rst
 150   ├── pw_docgen
 151   │   └── docgen.rst
 152   └── pw_preprocessor
 153       └── docs.rst
 154
 155 This is the documentation tree which gets passed to Sphinx to build HTML output.
 156 Imports within documentation files must be relative to this structure. In
 157 practice, relative imports from within modules' documentation groups are
 158 identical to the project's directory structure. The only special case is the
 159 top-level ``index.rst`` file's imports; they must start from the project's build
 160 root.