1.. _docs-contrib-docs-modules: 2 3================================== 4Module docs contributor guidelines 5================================== 6Read this page if you're writing documentation for a Pigweed module. 7This page shows you how to create high-quality module documentation. 8 9.. _#docs: https://discord.com/channels/691686718377558037/1111766977950797824 10 11Please start a discussion in the `#docs`_ channel of the Pigweed Discord 12for any questions or comments related to writing module docs. 13 14.. _docs-contrib-docs-modules-quickstart: 15 16---------- 17Quickstart 18---------- 19Follow these instructions and you're 95% done! 20 21.. _docs-contrib-docs-modules-quickstart-goldens: 22 23Emulate the golden module docs 24============================== 25Decide whether your module falls into the "simple", "backend", or "complex" 26category, and then just emulate the provided "golden examples" when writing 27your own module's docs: 28 29* **Simple** modules generally have small API surfaces, support only one 30 programming language, and can be completely documented in less than 2000 31 words. Golden examples: 32 33 * :ref:`module-pw_span` 34 * :ref:`module-pw_result` 35 * :ref:`module-pw_alignment` 36 37* **Backend** modules implement the facade or interface of another module. 38 Golden examples: 39 40 * :ref:`module-pw_i2c_rp2040` 41 42* **Complex** modules are everything else. In other words, if it's not a 43 simple module or a backend module, then it's a complex module. Golden 44 examples: 45 46 * :ref:`module-pw_hdlc` 47 * :ref:`module-pw_status` 48 * :ref:`module-pw_unit_test` 49 50Simple and backend modules should only have one page of documentation, 51``//pw_*/docs.rst``. Complex modules might need multiple pages of 52documentation. See :ref:`docs-contrib-docs-modules-theory-multi`. 53 54.. _docs-contrib-docs-modules-metadata: 55 56Add metadata 57============ 58Create your module's metadata: 59 601. Add a ``pigweed-module`` directive right after the title in your 61 module's ``docs.rst`` page: 62 63 .. code-block:: rst 64 65 ==== 66 pw_* 67 ==== 68 .. pigweed-module:: 69 :name: pw_* 70 712. Add metadata for your module in ``//docs/module_metadata.json``. 72 See ``//docs/module_metadata_schema.json`` for the schema 73 definition. 74 75 .. code-block:: json 76 77 { 78 "pw_alignment": { 79 "tagline": "Natural object alignment, guaranteed", 80 "status": "stable", 81 "languages": [ 82 "C++17" 83 ] 84 } 85 } 86 87 The ``tagline`` should concisely summarize your module's value proposition. 88 893. Add a ``pigweed-module-subpage`` directive right after the title 90 in each of your other docs pages (if your module has multiple docs 91 pages): 92 93 .. code-block:: rst 94 95 ============= 96 API reference 97 ============= 98 .. pigweed-module-subpage:: 99 :name: pw_* 100 101.. _docs-contrib-docs-modules-quickstart-usage: 102 103Demonstrate basic code usage 104============================ 105If your module provides an API, provide a code example after your 106module metadata that demonstrates basic usage of your API. 107 108.. _docs-contrib-docs-modules-quickstart-build: 109 110Show build system setup 111======================= 112If your module requires build system setup, make sure your 113quickstart section provides setup instructions for *all* of 114Pigweed's supported build systems: 115 116* Bazel 117* GN 118* CMake 119 120.. _docs-contrib-docs-modules-quickstart-reference: 121 122Auto-generate complete API references 123===================================== 124.. inclusive-language: disable 125 126.. _autodoc: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html 127 128.. inclusive-language: enable 129 130If your module has a C++ API, use :ref:`Doxygen <docs-style-doxygen>` to 131auto-generate your API reference. For a Python API use `autodoc`_. 132 133.. tip:: 134 135 Code samples make your class, function, and method references **much** 136 more usable and helpful! 137 138.. _docs-contrib-docs-modules-theory: 139 140------------------- 141Theory of operation 142------------------- 143This section explains the theory behind the module docs contributor 144guidelines. It's intended for the maintainers of the guidelines. If 145you're just writing docs for a module you own you don't need to read the 146theory of operation. But if you're curious about details, history, and 147rationale, you'll find that context here. 148 149.. _docs-contrib-docs-modules-theory-single: 150 151Single-page ordering 152==================== 153If the module only has a single page of documentation (``docs.rst``) 154the sections should be ordered like this: 155 156* :ref:`docs-contrib-docs-modules-theory-sales` 157* :ref:`docs-contrib-docs-modules-theory-quickstart` 158* :ref:`docs-contrib-docs-modules-theory-guides` 159* :ref:`docs-contrib-docs-modules-theory-reference` 160* :ref:`docs-contrib-docs-modules-theory-design` 161* :ref:`docs-contrib-docs-modules-theory-roadmap` 162* :ref:`docs-contrib-docs-modules-theory-size` 163 164The sales pitch must come first, followed by the quickstart instructions. 165Everything else beyond that is optional and can be rearranged in whatever way 166seems to flow best. 167 168The file must be located at ``//pw_*/docs.rst``. 169 170.. _docs-contrib-docs-modules-theory-multi: 171 172Multi-page ordering 173=================== 174If the module has multiple pages of documentation the pages should 175be ordered like this: 176 177.. list-table:: 178 :header-rows: 1 179 180 * - Page Title 181 - Filename 182 - Description 183 * - ``pw_*`` 184 - ``docs.rst`` 185 - The :ref:`docs-contrib-docs-modules-theory-sales` content. 186 * - ``Quickstart & guides`` 187 - ``guides.rst`` 188 - The :ref:`docs-contrib-docs-modules-theory-quickstart` content followed 189 by the :ref:`docs-contrib-docs-modules-theory-guides` content. See the 190 note below. 191 * - ``API reference`` 192 - ``api.rst`` 193 - The :ref:`docs-contrib-docs-modules-theory-reference` content. 194 * - ``Design & roadmap`` 195 - ``design.rst`` 196 - The :ref:`docs-contrib-docs-modules-theory-design` content. See the 197 note below. 198 * - ``Code size analysis`` 199 - ``size.rst`` 200 - The :ref:`docs-contrib-docs-modules-theory-size` content. 201 202The sales pitch and quickstart instructions are required. Everything else 203is optional and can be rearranged in whatever way seems to flow best. 204 205You can split ``Quickstart & guides`` into 2 docs if that works better for 206your module. The filenames should be ``get_started.rst`` and ``guides.rst``. 207 208``Design & roadmap`` can also be split into 2 docs. The filenames should be 209``design.rst`` and ``roadmap.rst``. 210 211.. _docs-contrib-docs-modules-theory-sales: 212 213Sales pitch 214=========== 215The sales pitch should: 216 217* Assume that the reader is an embedded developer. 218* Clearly explain how the reader's work as an embedded developer 219 will improve if they adopt the module. 220* Provide a code sample demonstrating one of the most important 221 problems the module solves. (Only required for modules that expose 222 an API.) 223 224.. _docs-contrib-docs-modules-theory-quickstart: 225 226Quickstart 227========== 228The quickstart instructions should: 229 230* Show how to get set up in Bazel, GN, and CMake. 231* Present Bazel instructions first. 232* Clearly state when a build system isn't supported. 233* Format the instructions with the ``.. tab-set::`` directive. See 234 ``//pw_string/guide.rst`` for an example. The Bazel instructions are 235 presented in the first tab, the GN instructions in the next, and so on. 236* Demonstrate how to complete a common use case. See the next paragraph. 237 238If your quickstart content is on the same page as your guides, then the 239quickstart section doesn't need to demonstrate a common use case. The reader 240can just scroll down and see how to complete common tasks. If your quickstart 241content is a standalone page, it should demonstrate how to complete a common 242task. The reader shouldn't have to dig around multiple docs just to figure out 243how to do something useful with the module. 244 245.. _docs-contrib-docs-modules-theory-guides: 246 247Guides 248====== 249The guides should: 250 251* Focus on how to solve real-world problems with the module. See 252 `About how-to guides <https://diataxis.fr/how-to-guides/>`_. 253 254.. _docs-contrib-docs-modules-theory-reference: 255 256API reference 257============= 258The API reference should: 259 260* Be auto-generated from :ref:`docs-style-doxygen` (for C++ / C APIs) or 261 `autodoc`_ (for Python APIs). 262* Provide a code example demonstrating how to use the class, at minimum. 263 Consider whether it's also helpful to provide more granular examples 264 demonstrating how to use each method, variable, etc. 265 266The typical approach is to order everything alphabetically. Some module docs 267group classes logically according to the tasks they're related to. We don't 268have a hard guideline here because we're not sure one of these approaches is 269universally better than the other. 270 271.. _docs-contrib-docs-modules-theory-design: 272 273Design 274====== 275The design content should: 276 277* Focus on `theory of operation <https://en.wikipedia.org/wiki/Theory_of_operation>`_ 278 or `explanation <https://diataxis.fr/explanation/>`_. 279 280.. _docs-contrib-docs-modules-theory-roadmap: 281 282Roadmap 283======= 284The roadmap should: 285 286* Focus on things known to be missing today that could make sense in the 287 future. The reader should be encouraged to talk to the Pigweed team. 288 289The roadmap should not: 290 291* Make very definite guarantees that a particular feature will ship by a 292 certain date. You can get an exception if you really need to do this, but 293 it should be avoided in most cases. 294 295.. _docs-contrib-docs-modules-theory-size: 296 297Size analysis 298============= 299The size analysis should: 300 301* Be auto-generated. See the ``pw_size_diff`` targets in ``//pw_string/BUILD.gn`` 302 for examples. 303 304The size analysis is elevated to its own section or page because it's a very 305important consideration for many embedded developers. 306