| .. _module-pw_docgen: | |
| --------- | |
| pw_docgen | |
| --------- | |
| The docgen module provides tools to generate documentation for Pigweed-based | |
| projects, and for Pigweed itself. | |
| Pigweed-based projects typically use a subset of Pigweed's modules and add their | |
| own product-specific modules on top of that, which may have product-specific | |
| documentation. Docgen provides a convenient way to combine all of the relevant | |
| documentation for a project into one place, allowing downstream consumers of | |
| release bundles (e.g. factory teams, QA teams, beta testers, etc.) to have a | |
| unified source of documentation early on. | |
| The documentation generation is integrated directly into the build system. Any | |
| build target can depend on documentation, which allows it to be included as part | |
| of a factory release build, for example. Additionally, documentation itself can | |
| depend on other build targets, such as report cards for binary size/profiling. | |
| Any time the code is changed, documentation will be regenerated with the updated | |
| reports. | |
| Documentation overview | |
| ====================== | |
| Each Pigweed module provides documentation describing its functionality, use | |
| cases, and programming API. | |
| Included in a module's documentation are report cards which show an overview of | |
| the module's size cost and performance benchmarks. These allow prospective users | |
| to evaluate the impact of including the module in their projects. | |
| Build integration | |
| ================= | |
| Pigweed documentation files are written in `reStructuredText`_ format and | |
| rendered to HTML using `Sphinx`_ through Pigweed's GN build system. | |
| .. _reStructuredText: http://docutils.sourceforge.net/rst.html | |
| .. inclusive-language: ignore | |
| .. _Sphinx: http://www.sphinx-doc.org/en/master | |
| There are additonal Sphinx plugins used for rendering diagrams within | |
| reStructuredText files including: | |
| * `Blockdiag <http://blockdiag.com/>`_ via these sphinxcontrib packages: | |
| * `sphinxcontrib-blockdiag | |
| <https://pypi.org/project/sphinxcontrib-blockdiag/>`_ | |
| * `sphinxcontrib-actdiag <https://pypi.org/project/sphinxcontrib-actdiag/>`_ | |
| * `sphinxcontrib-nwdiag <https://pypi.org/project/sphinxcontrib-nwdiag/>`_ | |
| * `sphinxcontrib-seqdiag <https://pypi.org/project/sphinxcontrib-seqdiag/>`_ | |
| * `mermaid <https://mermaid-js.github.io/>`_ via the `sphinxcontrib-mermaid | |
| <https://pypi.org/project/sphinxcontrib-mermaid/>`_ package. | |
| Documentation source and asset files are placed alongside code within a module | |
| and registered as a ``pw_docgen_group`` target within a ``BUILD.gn`` file. These | |
| groups become available for import within a special documentation generation | |
| target, which accumulates all of them and renders the resulting HTML. This | |
| system can either be used directly within Pigweed, or integrated into a | |
| downstream project. | |
| GN templates | |
| ------------ | |
| pw_doc_group | |
| ____________ | |
| The main template for defining documentation files is ``pw_doc_group``. It is | |
| used to logically group a collection of documentation source files and assets. | |
| Each Pigweed module is expected to provide at least one ``pw_doc_group`` target | |
| defining the module's documentation. A ``pw_doc_group`` can depend on other | |
| groups, causing them to be built with it. | |
| **Arguments** | |
| * ``sources``: RST documentation source files. | |
| * ``inputs``: Additional resources required for the docs (images, data files, | |
| etc.) | |
| * ``group_deps``: Other ``pw_doc_group`` targets required by this one. | |
| * ``report_deps``: Report card generating targets (e.g. ``pw_size_report``) on | |
| which the docs depend. | |
| **Example** | |
| .. code:: | |
| pw_doc_group("my_doc_group") { | |
| sources = [ "docs.rst" ] | |
| inputs = [ "face-with-tears-of-joy-emoji.svg" ] | |
| group_deps = [ ":sub_doc_group" ] | |
| report_deps = [ ":my_size_report" ] | |
| } | |
| pw_doc_gen | |
| __________ | |
| The ``pw_doc_gen`` template creates a target which renders complete HTML | |
| documentation for a project. It depends on registered ``pw_doc_group`` targets | |
| and creates an action which collects and renders them. | |
| To generate the complete docs, the template also requires a ``conf.py`` file | |
| configuring Sphinx's output, and a top level ``index.rst`` for the main page of | |
| the documentation. These are added at the root level of the built documentation | |
| to tie everything together. | |
| **Arguments** | |
| * ``conf``: Path to the ``conf.py`` to use for Sphinx. | |
| * ``index``: Path to the top-level ``index.rst`` file. | |
| * ``output_directory``: Directory in which to render HTML output. | |
| * ``deps``: List of all ``pw_doc_group`` targets required for the documentation. | |
| **Example** | |
| .. code:: | |
| pw_doc_gen("my_docs") { | |
| conf = "//my_docs/conf.py" | |
| index = "//my_docs/index.rst" | |
| output_directory = target_gen_dir | |
| deps = [ | |
| "//my_module:my_doc_group", | |
| ] | |
| } | |
| Generating documentation | |
| ------------------------ | |
| All source files listed under a ``pw_doc_gen`` target and its ``pw_doc_group`` | |
| dependencies get copied out into a directory structure mirroring the original | |
| layout of the modules in which the sources appear. This is demonstrated below | |
| using a subset of Pigweed's core documentation. | |
| Consider the following target in ``$dir_pigweed/docs/BUILD.gn``: | |
| .. code:: | |
| pw_doc_gen("docs") { | |
| conf = "conf.py" | |
| index = "index.rst" | |
| output_directory = target_gen_dir | |
| deps = [ | |
| "$dir_pw_bloat:docs", | |
| "$dir_pw_docgen:docs", | |
| "$dir_pw_preprocessor:docs", | |
| ] | |
| } | |
| A documentation tree is created under the output directory. Each of the sources | |
| and inputs in the target's dependency graph is copied under this tree in the | |
| same directory structure as they appear under the root GN build directory | |
| (``$dir_pigweed`` in this case). The ``conf.py`` and ``index.rst`` provided | |
| directly to the ``pw_doc_gen`` template are copied in at the root of the tree. | |
| .. code:: | |
| out/gen/docs/pw_docgen_tree/ | |
| ├── conf.py | |
| ├── index.rst | |
| ├── pw_bloat | |
| │ ├── bloat.rst | |
| │ └── examples | |
| │ └── simple_bloat.rst | |
| ├── pw_docgen | |
| │ └── docgen.rst | |
| └── pw_preprocessor | |
| └── docs.rst | |
| This is the documentation tree which gets passed to Sphinx to build HTML output. | |
| Imports within documentation files must be relative to this structure. In | |
| practice, relative imports from within modules' documentation groups are | |
| identical to the project's directory structure. The only special case is the | |
| top-level ``index.rst`` file's imports; they must start from the project's build | |
| root. |