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.

There are additonal Sphinx plugins used for rendering diagrams within reStructuredText files including:

Documentation source and asset files are placed alongside code within a module and registered as a pw_doc_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

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

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:

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.

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.