Skip to content

docs: give the Sphinx docs the selfpatch.ai look - #715

Open
loehub wants to merge 2 commits into
mainfrom
docs/brand-theme
Open

loehub wants to merge 2 commits into
mainfrom
docs/brand-theme

Conversation

@loehub

@loehub loehub commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

Pull Request

Summary

Restyles the docs site (selfpatch.github.io/ros2_medkit) to match selfpatch.ai and the new README. It keeps the Read the Docs theme, its layout and its navigation, so only the look changes.

  • Fonts: Oxanium for headings, Inter for body text, IBM Plex Mono for code. They're self-hosted under docs/_static/fonts rather than loaded from Google Fonts, about 110 KB in total, each with its upstream licence file:
    • Inter and Oxanium: Latin subsets, which the OFL allows because neither reserves its font name.
    • IBM Plex Mono: IBM's own unmodified IBMPlexMono-Regular.woff2 from @ibm/plex-mono 2.5.0, because "Plex" is a reserved name. It also covers the box-drawing characters the directory trees use.
  • Sidebar: graphite, with the selfpatch.ai wordmark above the project name. Section labels are sentence case instead of uppercase blue. The open section sits on a slightly raised panel and the current page is in acid.
  • Content:
    • Links are forest green.
    • Inline code is ink on light grey instead of red.
    • Code blocks and notes are soft rounded panels; tips, warnings and danger keep tinted backgrounds.
    • Tables use hairline rows without zebra stripes or cell borders.
    • Cards are light grey panels without shadows.
    • sphinx-design tabs are ink instead of the default blue.
  • Favicon: the selfpatch.ai icon.
  • sphinx-needs tables: the existing DataTables fixes stay as they were, now in the same colours.
  • Home page cards: the Quick Links grid gets an even 1.5rem gap both ways. It had none vertically, so the filled cards touched. Card grids now line up with the headings, text and code blocks around them.

Changes are limited to docs/_static/custom.css, two lines in docs/conf.py (html_logo, html_favicon), one :gutter: line in docs/index.rst and the static files above. The content width setting is unchanged.


Issue

No linked issue. Suggested by the team in review chat.


Type

  • Bug fix
  • New feature or tests
  • Breaking change
  • Documentation only

Testing

  • Built the docs locally with the pinned versions (Sphinx 8.2.3, sphinx-rtd-theme 3.1.0, sphinx-needs 6.3.0, sphinx-design 0.7.0) and served them.
  • Checked the home page, Installation (tables, notes, inline code, code blocks), Getting Started, the Verification and Coverage pages (sphinx-needs, tabs, DataTables) and phone width.
  • No new warnings. Doxygen and PlantUML weren't installed locally, so the API and diagram pages still showed their existing warnings. CI installs both and builds with -W.

To reproduce:

pip install -e docs/.[dev]
sphinx-build -b html docs docs/_build/html

Checklist

  • Breaking changes are clearly described (and announced in docs / changelog if needed)
  • Tests were added or updated if needed
  • Docs were updated if behavior or public API changed

Restyle the docs site to match selfpatch.ai and the README, keeping the
Read the Docs theme, its layout and navigation, so nothing moves for
readers or for the build.

- Oxanium for headings, Inter for body text and IBM Plex Mono for code,
  self-hosted under _static/fonts (SIL OFL, licences included) rather
  than fetched from Google Fonts.
- A graphite sidebar with the selfpatch.ai wordmark above the project
  name, sentence-case section labels instead of uppercase blue, the open
  section on a raised panel and the current page in acid.
- Forest links, inline code in ink on chalk instead of red, code blocks
  and admonitions as soft rounded panels, hairline tables without zebra
  rows or cell borders, chalk cards without shadows, and sphinx-design
  tabs in ink instead of the default blue.
- The home page cards get an even 1.5rem gap both ways (the grid had
  none vertically, so the filled cards touched), and card grids line up
  with the headings, text and code blocks around them.
- The selfpatch.ai icon as the favicon.

The DataTables fixes for the sphinx-needs tables stay as they were, now
in the same colours.
@bburda
bburda self-requested a review October 5, 2026 19:03
Comment thread docs/_static/fonts/OFL-IBMPlexMono.txt
Comment thread docs/_static/fonts/OFL-Inter.txt Outdated
IBM Plex Mono is licensed under the OFL with Reserved Font Name "Plex",
so a modified copy may not keep that name without IBM's permission. The
bundled file was a Latin subset Google Fonts made, which still calls
itself IBM Plex Mono. Replace it with IBMPlexMono-Regular.woff2 from
IBM's @ibm/plex-mono 2.5.0 package, byte for byte (the npm tarball's
sha512 checked against the registry), and ship IBM's LICENSE.txt with it.
The full font also has the box-drawing characters the directory trees in
the docs use, which the subset lacked.

OFL-Inter.txt carried the copyright line from the Google Fonts copy
(2020). The font file and rsms/inter's LICENSE.txt both say "Copyright
(c) 2016 The Inter Project Authors", so use the upstream file.

Inter and Oxanium reserve no font name, so their Latin subsets may keep
their names under the OFL. OFL-Oxanium.txt already matches upstream.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants