Migration of theme to modern responsive theme

[willingc]

python/devguide#679

[JulienPalard]

There's two PRs opened on python-docs-theme to modernize the current theme:

• responsive
• dark theme

But I do not have the CSS-fu to help here, I can only test them.

Beware if we want to switch theme, they'll have to support our language and version switchers, which is currently probably too convoluted :

• cpython's tools/templates/layout.html add placeholders in the rootrellink block.
• docsbuild switch (which knows the list of versions and languages) injects a switchers.js right before </body>

In the other hand, rootrellink is from sphinx, not the theme, so it could by chance just work.

[JulienPalard]

@pradyunsg, quoting you to continue in this relevant thread:

If there's genuine interest in the modernization of the Python documentation and python-docs-theme (i.e. fairly major changes to look more like from-this-decade), I am very very interested in helping with that. :)

I think we all agree that the theme should evolve. Even from an SEO point of view (mobile-first ranking in SERPs) it's important.

As you understood, my front-end skill is absent, that's why I refrained to comment on python/python-docs-theme#55 for example (which I followed carefully). I also avoid to merge PRs in the theme without approbations of skilled front-end developers: I can test the visual quality, but not the implementation quality.

But if you need any help understanding how the language and version switchers work, or if they need to be changed, I'll gladly help here. I recently added a github workflow on python-docs-theme to build with the version and language switchers (html downloadable as a build artifact).

[Mariatta]

I admit that I also don't have front end JS/CSS skills. I've been following all the discussions in python-docs-theme repo as well. I. just don't know how to test or how to review those changes.

[willingc]

I can take a look at the existing python-docs-theme along with Furo to determine if it makes more sense to add Python-specific stuff to Furo or vice versa. One of the nice things about Furo is it was designed with Sphinx 3.x in mind so it will bake in the advantage of updates from that, at least from a theme perspective. I've been using Furo in other projects and have been very happy with it in those.

[pradyunsg]

language and version switchers

Yup yup! IIUC, those are the main CPython-docs-specific thing, and there's decent complexity in the build scripts due to this. Let me know if there's something else to think of when working on this. :)

I'll take a closer look at the build scripts over this long weekend! FWIW, I'm on the PSF Slack, so if it's needed at some point, it would be possible to have a fast-than-GitHub-comments chat there.

Also, If there's no "strict" time pressure, I'm working on https://github.com/pradyunsg/sphinx-basic-ng/, which might actually be a better base to build upon than Furo. That + Furo's content styling basically describes the other Sphinx theme I'm working on right now. :)

[JulienPalard]

I just don't know how to test

I just made this very simple: the python-docs-theme now provide a cpython built documentation as a check artifact. It even has the version and language switchers, exactly like it's built on docs.python.org (with all the dirty tricks I'm not proud of, like editing HTML using sed).

Next step would be to temporarily (has to be defined...) host artifacts somewhere (has to be defined...) and make a bot to give the link in the PR?

[hugovk]

Next step would be to temporarily (has to be defined...) host artifacts somewhere (has to be defined...) and make a bot to give the link in the PR?

How about including some test docs that uses the theme, and deploy to Read the Docs? We could then enable previews from PRs, and it would automatically build and deploy using the theme to a test RTD site, making it easy to test the PR on desktop and mobile.

For example, python/devguide#679 has a preview at https://cpython-devguide--679.org.readthedocs.build/

[JulienPalard]

I have no idea how incompatible our language and version switchers are with RTD though.

[willingc]

I believe that RTD has a pretty comprehensive version switcher. We should reach out to Eric Holscher and team.

[pradyunsg]

I just flagged this discussion to @humitos, as he's one of the folks in RTD. :)

[humitos]

Hi all! I don't know exactly how the build process for docs.python.org works, but IIRC what I saw once was a set of custom scripts (to generate the version selector) together with a sphinx-build call.

Unfortunately, Read the Docs does not officially support executing arbitrary commands (*). However, if those extra commands are only used to generate the version selector, they probably won't be needed if the docs are hosted at RTD since the version selector is automatically managed/created by RTD with all the active versions for the project.

When building on RTD with our own Sphinx theme (sphinx-rtd-theme) the version selector is nicely integrated into the theme (bottom left). On the other hand, when building with other themes, the version selector is shown as a floating sticky element (bottom right).

Examples:

• Spanish translation of Python official's documentation
• Python's official documentation on Read the Docs + sphinx-hoverxref extension installed

As you can see there, the version selector from CPython docs is not displayed but the RTD floating sticky element at the bottom right is shown instead.

That said, I'd add that we are working on a new flyout and footer API to allow Sphinx Theme's authors to manipulate the data that RTD uses to generate the version selector as they want and provide a better integration with their themes.

(*) you can by adding them in the conf.py as a hacky workaround, tho.

---

If you only want fast previews, I'd suggest creating a project on RTD, enabling PR builder, and discuss the changes over the rendered version. I think the only downside that this has is that your version selector won't be shown but still, it will work for 90% of the theme/style discussions I suppose.

If you eventually want to migrate your docs to RTD --which I think it's not your goal for now-- we should check that all the requirements that you currently have are supported on Read the Docs (e.g. I already known that multiple PDF outputs are not supported).

In any case, whatever you decide regarding RTD, feel free to ping me and let me know if I can help somehow. I'm happy to help here.

[JulienPalard]

For info, here's how the current language and version switchers in docs.python.org are working:

• The theme places an empty div <div class="language_switcher_placeholder"></div> so we can play around later.
• The theme have the CSS style for those switchers.
• The docsbuild script is the only source of truth about known versions and known languages.
• The docsbuild script creates a JS file with this list of languages and versions, what's needed to create the DOM elements, and the event handlers to do the switches.
• And now for the ugly part: the docsbuild script injects the JS on every pages.

Here are some ideas on how to enhance this: #4

[pradyunsg]

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