1.. _contrib-docs-guides: 2 3======================= 4Docs contributor guides 5======================= 6This page explains how to do common tasks related to: 7 8* Authoring ``pigweed.dev`` content 9* Customizing and maintaining the ``pigweed.dev`` website 10 11.. important:: 12 13 This guide is incomplete. If you need to make content updates **right now**, 14 follow the guidance in :ref:`docs-get-started-upstream`. The rest of this 15 quickstart focuses on the new, work-in-progress Bazel-based docs system. 16 You should ignore this quickstart unless a Pigweed teammate has specifically 17 pointed you here. 18 19.. _contrib-docs-guides-setup: 20 21----------------------------------- 22Set up your development environment 23----------------------------------- 24#. Complete :ref:`docs-first-time-setup`. 25 26#. :ref:`docs-install-bazel`. 27 28.. _contrib-docs-guides-build: 29 30-------------- 31Build the docs 32-------------- 33.. code-block:: console 34 35 bazelisk build //docs/... 36 37.. _contrib-docs-guides-build-tree: 38 39Build the underlying sources directory 40====================================== 41Use this command to verify that files are being copied over to 42the expected location: 43 44.. code-block:: console 45 46 bazelisk build //docs:docs/_sources 47 48.. _contrib-docs-guides-build-sphinx: 49 50Directly run sphinx-build 51========================= 52.. inclusive-language: disable 53.. _sphinx-build: https://www.sphinx-doc.org/en/master/man/sphinx-build.html 54.. inclusive-language: enable 55 56Use this command to mimic directly running `sphinx-build`_ 57from a non-Bazel context. For example, you could set a breakpoint 58in your Sphinx extension, then run this command, then step through 59the code with ``pdb``. 60 61.. code-block:: console 62 63 bazelisk run //docs:docs.run 64 65.. _contrib-docs-guides-preview: 66 67------------------------ 68Locally preview the docs 69------------------------ 70.. code-block:: console 71 72 bazelisk run //docs:docs.serve 73 74A message like this should get printed to ``stdout``: 75 76.. code-block:: console 77 78 Serving... 79 Address: http://0.0.0.0:8000 80 Serving directory: /home/kayce/pigweed/pigweed/bazel-out/k8-fastbuild/bin/docs/docs/_build/html 81 url: file:///home/kayce/pigweed/pigweed/bazel-out/k8-fastbuild/bin/docs/docs/_build/html 82 Server CWD: /home/kayce/.cache/bazel/_bazel_kayce/9659373b1552c281136de1c8eeb3080d/execroot/_main/bazel-out/k8-fastbuild/bin/docs/docs.serve.runfiles/_main 83 84You can access the rendered docs at the URL that's printed next to 85**Address**. 86 87.. _contrib-docs-guides-site: 88 89--------------- 90Website updates 91--------------- 92.. _Sphinx: https://www.sphinx-doc.org 93 94This section discusses how to make frontend and backend website changes 95to ``pigweed.dev``, Pigweed's main documentation website, and how to 96customize `Sphinx`_, the website generator that powers ``pigweed.dev``. 97 98.. _contrib-docs-guides-site-redirects: 99 100Create redirects 101================ 102.. _sphinx-reredirects: https://pypi.org/project/sphinx-reredirects/ 103 104``pigweed.dev`` supports client-side HTML redirects. The redirects are powered 105by `sphinx-reredirects`_. 106 107To create a redirect: 108 109#. Open ``//docs/conf.py``. 110 111.. _Usage: https://documatt.com/sphinx-reredirects/usage.html 112 113#. Add your redirect to the ``redirects`` dict. See the 114 `Usage`_ section from the ``sphinx-reredirects`` docs. 115 116 * The redirect should be relative to the source path (i.e. the path that 117 needs to get redirected). 118 119 * The target path (i.e. the destination path that the source path should 120 redirect to) should include the full HTML filename to ensure that the 121 redirects also work during local development. In other words, prefer 122 ``./example/docs.html`` over ``./example/``. 123 124For each URL that should be redirected, ``sphinx-reredirects`` auto-generates 125HTML like this: 126 127.. code-block:: html 128 129 <html> 130 <head> 131 <meta http-equiv="refresh" content="0; url=pw_sys_io_rp2040/"> 132 </head> 133 </html> 134 135.. _meta refresh and its HTTP equivalent: https://developers.google.com/search/docs/crawling-indexing/301-redirects#metarefresh 136 137.. note:: 138 139 Server-side redirects are the most robust solution, but client-side 140 redirects are good enough for our needs: 141 142 * Client-side redirects are supported in all browsers and should 143 therefore work for all real ``pigweed.dev`` readers. 144 145 * Client-side redirects were much easier and faster to implement. 146 147 * Client-side redirects can be stored alongside the rest of the 148 ``pigweed.dev`` source code. 149 150 * Google Search interprets the kind of client side redirects that we use 151 as permanent redirects, which is the behavior we want. See 152 `meta refresh and its HTTP equivalent`_. The type of client-side redirect 153 we used is called a "instant ``meta refresh`` redirect" in that guide. 154 155.. _contrib-docs-guides-site-urls: 156 157Auto-generated source code and issues URLS 158========================================== 159In the site nav there's a ``Source code`` and ``Issues`` URL for each module. 160These links are auto-generated. The auto-generation logic lives in 161``//pw_docgen/py/pw_docgen/sphinx/module_metadata.py``. 162 163.. _contrib-docs-guides-site-copy: 164 165Copy-to-clipboard feature on code blocks 166======================================== 167.. _sphinx-copybutton: https://sphinx-copybutton.readthedocs.io/en/latest/ 168.. _Remove copybuttons using a CSS selector: https://sphinx-copybutton.readthedocs.io/en/latest/use.html#remove-copybuttons-using-a-css-selector 169 170The copy-to-clipboard feature on code blocks is powered by `sphinx-copybutton`_. 171 172``sphinx-copybutton`` recognizes ``$`` as an input prompt and automatically 173removes it. 174 175There is a workflow for manually removing the copy-to-clipboard button for a 176particular code block but it has not been implemented yet. See 177`Remove copybuttons using a CSS selector`_. 178 179.. _contrib-docs-guides-site-fonts: 180 181Fonts and typography 182==================== 183``pigweed.dev`` is taking an iterative approach to its fonts and typography. 184See :bug:`353530954` for context, examples of how to update fonts, and to 185leave feedback. 186 187.. _Typography: https://m3.material.io/styles/typography/fonts 188 189Rationale for current choices: 190 191* Headings: ``Lato``. Per UX team's recommendation. 192* Copy: ``Noto Sans``. ``Noto`` is one of two fonts recommended by Material 193 Design 3. It seems to complement ``Lato`` well. See `Typography`_. 194* Code: ``Roboto Mono``. Also per UX team's recommendation. ``Roboto Mono`` 195 is mature and well-established in this space. 196 197.. _contrib-docs-guides-site-search: 198 199Inline search 200============= 201In the header of every page there's a search box. When you focus that search 202box (or press :kbd:`Ctrl+K`) a search modal appears. After you type some 203text in the search modal, you immediately see results below your search query. 204The inline search results UX is Pigweed-specific custom logic. That code 205lives in ``//docs/_static/js/pigweed.js``. If :bug:`363034219` is successfully 206completed then we will remove this custom code from the Pigweed repo. 207