pigweed.dev#

How to make frontend and backend website changes to pigweed.dev, Pigweed’s main documentationw website, and how to change the functionality of Sphinx, the website generator that powers pigweed.dev.

Create redirects#

pigweed.dev supports client-side HTML redirects. The redirects are powered by sphinx-reredirects.

To create a redirect:

Open //docs/conf.py.

Add your redirect to the redirects dict. See the Usage section from the sphinx-reredirects docs.
- The redirect should be relative to the source path (i.e. the path that needs to get redirected).
- The target path (i.e. the destination path that the source path should redirect to) should include the full HTML filename to ensure that the redirects also work during local development. In other words, prefer ./example/docs.html over ./example/ because the latter assumes the existence of a server that redirects ./example/ to ./example/docs.html.

For each URL that should be redirected, sphinx-reredirects auto-generates HTML like this:

<html>
  <head>
    <meta http-equiv="refresh" content="0; url=pw_sys_io_rp2040/">
  </head>
</html>

Note

Server-side redirects are the most robust solution, but client-side redirects are good enough for our needs:

Client-side redirects are supported in all browsers and should work therefore work for all real pigweed.dev readers.
Client-side redirects were much easier and faster to implement.
Client-side redirects can be stored alongside the rest of the pigweed.dev source code.
Google Search interprets the kind of client side redirects that we use as permanent redirects, which is the behavior we want. See meta refresh and its HTTP equivalent. The type of client-side redirect we used is called a “instant meta refresh redirect” in that guide.

Breadcrumbs#

The breadcrumbs at the top of each page (except the homepage) is implemented in //docs/layout/page.html. The CSS for this UI is in //docs/_static/css/pigweed.css under the .breadcrumbs and .breadcrumb classes.

Auto-generated source code and issues URLS#

In the site nav there’s a Source code and Issues URL for each module. These links are auto-generated. The auto-generation logic lives in //pw_docgen/py/pw_docgen/sphinx/module_metadata.py.

Copy-to-clipboard feature on code blocks#

The copy-to-clipboard feature on code blocks is powered by sphinx-copybutton.

sphinx-copybutton recognizes $ as an input prompt and automatically removes it.

There is a workflow for manually removing the copy-to-clipboard button for a particular code block but it has not been implemented yet. See Remove copybuttons using a CSS selector.

Site nav scrolling#

We have had recurring issues with scrolling on pigweed.dev. This section provides context on the issue and fix(es).

The behavior we want:

The page that you’re currently on should be visible in the site nav.
URLs with deep links (e.g. pigweed.dev/pw_allocator/#size-report) should instantly jump to the target section (e.g. #size-report).
There should be no scrolling animations anywhere on the site. Scrolls should happen instantly.

A few potential issues at play:

Our theme (Furo) has non-configurable scrolling logic. See furo.js.
There seems to be a race condition between Furo’s scrolling behavior and our text-to-diagram tool, Mermaid, which uses JavaScript to render the diagrams on page load. However, we also saw issues on pages that didn’t have any diagrams, so that can’t be the site-wide root cause.

Our current fix:

In //docs/_static/js/pigweed.js we manually scroll the site nav and main content via scrollTop. Note that we previously tried scrollIntoView but it was not an acceptable fix because the main content would always scroll down about 50 pixels, even when a deep link was not present in the URL. We also manually control when Mermaid renders its diagrams.
In //docs/_static/css/pigweed.css we use an aggressive CSS rule to ensure that scroll-behavior is set to auto (i.e. instant scrolling) for all elements on the site.

Background: