1.. _docs-contrib-docs-website: 2 3=========== 4pigweed.dev 5=========== 6How to make frontend and backend website changes to ``pigweed.dev``, 7Pigweed's main documentationw website, and how to change the functionality 8of Sphinx, the website generator that powers ``pigweed.dev``. 9 10.. _docs-contrib-docs-website-redirects: 11 12---------------- 13Create redirects 14---------------- 15.. _sphinx-reredirects: https://pypi.org/project/sphinx-reredirects/ 16 17``pigweed.dev`` supports client-side HTML redirects. The redirects are powered 18by `sphinx-reredirects`_. 19 20To create a redirect: 21 22#. Open ``//docs/conf.py``. 23 24.. _Usage: https://documatt.com/sphinx-reredirects/usage.html 25 26#. Add your redirect to the ``redirects`` dict. See the 27 `Usage`_ section from the ``sphinx-reredirects`` docs. 28 29 * The redirect should be relative to the source path (i.e. the path that 30 needs to get redirected). 31 32 * The target path (i.e. the destination path that the source path should 33 redirect to) should include the full HTML filename to ensure that the 34 redirects also work during local development. In other words, prefer 35 ``./example/docs.html`` over ``./example/`` because the latter assumes 36 the existence of a server that redirects ``./example/`` to 37 ``./example/docs.html``. 38 39For each URL that should be redirected, ``sphinx-reredirects`` auto-generates 40HTML like this: 41 42.. code-block:: html 43 44 <html> 45 <head> 46 <meta http-equiv="refresh" content="0; url=pw_sys_io_rp2040/"> 47 </head> 48 </html> 49 50.. _meta refresh and its HTTP equivalent: https://developers.google.com/search/docs/crawling-indexing/301-redirects#metarefresh 51 52.. note:: 53 54 Server-side redirects are the most robust solution, but client-side 55 redirects are good enough for our needs: 56 57 * Client-side redirects are supported in all browsers and should work 58 therefore work for all real ``pigweed.dev`` readers. 59 60 * Client-side redirects were much easier and faster to implement. 61 62 * Client-side redirects can be stored alongside the rest of the 63 ``pigweed.dev`` source code. 64 65 * Google Search interprets the kind of client side redirects that we use 66 as permanent redirects, which is the behavior we want. See 67 `meta refresh and its HTTP equivalent`_. The type of client-side redirect 68 we used is called a "instant ``meta refresh`` redirect" in that guide. 69 70.. _docs-contrib-docs-website-breadcrumbs: 71 72----------- 73Breadcrumbs 74----------- 75.. _breadcrumbs: https://en.wikipedia.org/wiki/Breadcrumb_navigation 76 77The `breadcrumbs`_ at the top of each page (except the homepage) is implemented 78in ``//docs/layout/page.html``. The CSS for this UI is in 79``//docs/_static/css/pigweed.css`` under the ``.breadcrumbs`` and 80``.breadcrumb`` classes. 81 82.. _docs-contrib-docs-website-urls: 83 84------------------------------------------ 85Auto-generated source code and issues URLS 86------------------------------------------ 87In the site nav there's a ``Source code`` and ``Issues`` URL for each module. 88These links are auto-generated. The auto-generation logic lives in 89``//pw_docgen/py/pw_docgen/sphinx/module_metadata.py``. 90 91.. _docs-contrib-docs-website-copy: 92 93---------------------------------------- 94Copy-to-clipboard feature on code blocks 95---------------------------------------- 96.. _sphinx-copybutton: https://sphinx-copybutton.readthedocs.io/en/latest/ 97.. _Remove copybuttons using a CSS selector: https://sphinx-copybutton.readthedocs.io/en/latest/use.html#remove-copybuttons-using-a-css-selector 98 99The copy-to-clipboard feature on code blocks is powered by `sphinx-copybutton`_. 100 101``sphinx-copybutton`` recognizes ``$`` as an input prompt and automatically 102removes it. 103 104There is a workflow for manually removing the copy-to-clipboard button for a 105particular code block but it has not been implemented yet. See 106`Remove copybuttons using a CSS selector`_. 107 108.. _docs-site-scroll: 109 110------------------ 111Site nav scrolling 112------------------ 113We have had recurring issues with scrolling on pigweed.dev. This section 114provides context on the issue and fix(es). 115 116The behavior we want: 117 118* The page that you're currently on should be visible in the site nav. 119* URLs with deep links (e.g. ``pigweed.dev/pw_allocator/#size-report``) should 120 instantly jump to the target section (e.g. ``#size-report``). 121* There should be no scrolling animations anywhere on the site. Scrolls should 122 happen instantly. 123 124.. _furo.js: https://github.com/pradyunsg/furo/blob/main/src/furo/assets/scripts/furo.js 125 126A few potential issues at play: 127 128* Our theme (Furo) has non-configurable scrolling logic. See `furo.js`_. 129* There seems to be a race condition between Furo's scrolling behavior and our 130 text-to-diagram tool, Mermaid, which uses JavaScript to render the diagrams 131 on page load. However, we also saw issues on pages that didn't have any 132 diagrams, so that can't be the site-wide root cause. 133 134.. _scrollTop: https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollTop 135.. _scrollIntoView: https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView 136.. _scroll-behavior: https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-behavior 137 138Our current fix: 139 140* In ``//docs/_static/js/pigweed.js`` we manually scroll the site nav and main 141 content via `scrollTop`_. Note that we previously tried `scrollIntoView`_ 142 but it was not an acceptable fix because the main content would always scroll 143 down about 50 pixels, even when a deep link was not present in the URL. 144 We also manually control when Mermaid renders its diagrams. 145* In ``//docs/_static/css/pigweed.css`` we use an aggressive CSS rule 146 to ensure that `scroll-behavior`_ is set to ``auto`` (i.e. instant scrolling) 147 for all elements on the site. 148 149Background: 150 151* `Tracking issue <https://issues.pigweed.dev/issues/303261476>`_ 152* `First fix <https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/162410>`_ 153* `Second fix <https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/162990>`_ 154* `Third fix <https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/168555>`_ 155* `Fourth fix <https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/178591>`_ 156