Wyatt Hepler | f9fb90f | 2020-09-30 18:59:33 -0700 | [diff] [blame] | 1 | .. _module-pw_docgen: |
Alexei Frolov | 199045a | 2020-08-28 13:02:30 -0700 | [diff] [blame] | 2 | |
Wyatt Hepler | b82f995 | 2019-11-25 13:56:31 -0800 | [diff] [blame] | 3 | --------- |
| 4 | pw_docgen |
| 5 | --------- |
Alexei Frolov | 8ffcb91 | 2019-11-18 11:00:20 -0800 | [diff] [blame] | 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 |
Armando Montanez | 5464d5f | 2020-02-20 10:12:20 -0800 | [diff] [blame] | 147 | │ ├── bloat.rst |
| 148 | │ └── examples |
| 149 | │ └── simple_bloat.rst |
Alexei Frolov | 8ffcb91 | 2019-11-18 11:00:20 -0800 | [diff] [blame] | 150 | ├── pw_docgen |
Armando Montanez | 5464d5f | 2020-02-20 10:12:20 -0800 | [diff] [blame] | 151 | │ └── docgen.rst |
Alexei Frolov | 8ffcb91 | 2019-11-18 11:00:20 -0800 | [diff] [blame] | 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. |