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