Okay, so... I've definitely been nerd-sniped by this. Here's an update/brain-dump on how that's going. 😅

There's a video at the end too!

I've started working on a Sphinx theme, for documentation sets with the size and structure of Python's documentation. The initial working name is Lutra, which is what I'll use in this comment, but it is definitely subject to change. Here's the documentation sites I'm currently using, to draw inspirations from (additional suggestions welcome):

Furo (du'oh!)
Ionic Framework documentation
Just the Docs for Jekyll
mkdocs-material for MkDocs
Tailwind CSS documentation

My thought process for how things could work is: Lutra builds upon sphinx-basic-ng (more on this below) and becomes the base theme for python-docs-theme and pypa-docs-theme, with the python-docs-theme being only for Python's documentation. This model means we can get rid of documentation-related templates in CPython's source tree and specialise python-docs-theme to only be for Python, which may be super useful if we want to add build-time logic (in the Sphinx extension code for python-docs-theme), for generating the switchers (#4) or including the top bar from https://www.python.org/ (as I'd originally proposed in python/python-docs-theme#10).

(theme dependency tree -- status quo)

basic (built-in Sphinx theme)
╰─▶ default (built-in Sphinx theme)
    ╰─▶ python-docs-theme
        ╰─▶ pypa-docs-theme

(theme dependency tree -- what I'm currently thinking of)

basic (built-in Sphinx theme)
╰─▶ basic-ng
    ├─▶ [other themes]
    ╰─▶ lutra
        ├─▶ pypa-docs-theme
        ├─▶ python-docs-theme
        ╰─▶ [other themes]

As for sphinx-basic-ng -- that's something that will quite possibly be used by some other major themes in the Sphinx ecosystem (like sphinx-book-theme and pydata-sphinx-theme) -- I'm working closely with multiple theme authors/maintainers to figure out ways to reduce the repeated work, and have an actually thought out scaffold for this. See sphinx-basic-ng's repository/issue tracker if you're curious. I worked on it a bit last weekend and am pretty happy with where it is now, in terms of the actual implementation. It still needs a lot of documentation for theme authors, but slow-and-steady progress is the ongoing goal for all these things. And because video >> pictures >> words, here's a quick demo of sphinx-basic-ng, specifically the default behaviour of the fairly customisable scaffolding that comes with it:

Screen.Recording.2021-10-10.at.15.15.44.mov

Uh oh!

Description

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions