Lines Matching +full:build +full:- +full:docs
1 .. _module-pw_docgen:
6 .. pigweed-module::
9 ``pw_docgen`` provides tools to generate documentation for Pigweed-based
16 --------
18 --------
19 Pigweed-based projects typically use a subset of Pigweed's modules and add their
20 own product-specific modules on top of that, which may have product-specific
26 The documentation generation is integrated directly into the build system. Any
27 build target can depend on documentation, which allows it to be included as part
28 of a factory release build, for example. Additionally, documentation itself can
29 depend on other build targets, such as :ref:`report cards <module-pw_bloat>` for
40 -----------------
41 Build integration
42 -----------------
44 rendered to HTML using `Sphinx`_ through Pigweed's GN build system.
47 .. inclusive-language: ignore
48 .. _Sphinx: http://www.sphinx-doc.org/en/master
53 * `mermaid <https://mermaid-js.github.io/>`_ via the `sphinxcontrib-mermaid
54 <https://pypi.org/project/sphinxcontrib-mermaid/>`_ package.
57 and registered as a ``pw_doc_group`` target within a ``BUILD.gn`` file. These
67 ------------
77 * ``inputs``: Additional resources required for the docs (images, data files,
81 which the docs depend.
88 .. code-block::
91 sources = [ "docs.rst" ]
92 inputs = [ "face-with-tears-of-joy-emoji.svg" ]
98 ----------
103 To generate the complete docs, the template also requires a ``conf.py`` file
111 * ``index``: Path to the top-level ``index.rst`` file.
114 * ``python_metadata_deps``: Python-related dependencies that are only used as
116 documentation generation. This should rarely be used by non-Pigweed code.
120 .. code-block::
132 ------------------------
138 Consider the following target in ``$dir_pigweed/docs/BUILD.gn``:
140 .. code-block::
142 pw_doc_gen("docs") {
147 "$dir_pw_bloat:docs",
148 "$dir_pw_docgen:docs",
149 "$dir_pw_preprocessor:docs",
155 same directory structure as they appear under the root GN build directory
159 .. code-block::
161 out/gen/docs/pw_docgen_tree/
171 └── docs.rst
173 This is the documentation tree which gets passed to Sphinx to build HTML output.
177 top-level ``index.rst`` file's imports; they must start from the project's build
181 ---------------------
182 ``pw_docgen`` includes a web server that serves locally-generated documentation
183 at ``pw_docgen.docserver``. It supports hot-reloading, so the rendered docs in
186 In most cases, you will not need to run the docs server directly. Instead, it
187 will be run via :ref:`module-pw_watch`.
189 -----------------------------
191 -----------------------------
195 This module houses Pigweed-specific extensions for the Sphinx documentation
196 generator. Extensions are included and configured in ``docs/conf.py``.
200 See :ref:`docs-contrib-docs-modules-metadata`.
203 ---------------------------
204 ``module_metadata`` fixes the canonical URLs for ``*/docs.html`` pages. By
206 default canonical URL for ``//pw_string/docs.rst`` is
207 ``https://pigweed.dev/pw_string/docs.html``. The ``pigweed.dev``
210 ends in ``/docs.html`` such as
211 ``https://pigweed.dev/third_party/emboss/docs.html``. ``module_metadata`` fixes
215 After building the docs, the canonical URLs for all HTML pages can be verified
219 .. code-block:: console
221 grep '<link rel="canonical' out/docs/gen/docs/html/* -R
226 ---
229 <https://docutils.sourceforge.io/docs/ref/rst/roles.html>`__ that can be
232 .. code-block:: rst
239 ----------------
247 enabled or not in your build configuration. Typically, you would only enable
251 -------------------------------------
253 `pdb <https://docs.python.org/3/library/pdb.html>`_:
257 .. code-block::
261 #. Build ``python.install`` to install the code change into the bootstrap venv
262 (``environment/pigweed-venv/lib/python3.8/site-packages/pw_docgen``):
264 .. code-block::
266 ninja -C out python.install
268 #. Manually invoke Sphinx to build the docs and trigger your breakpoint:
270 .. code-block::
273 …sphinx-build -W -b html -d docs/gen/docs/help docs/gen/docs/pw_docgen_tree docs/gen/docs/html -v -…
275 You should see build output from Sphinx. The build should pause at your