You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@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).
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.
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.
Reacted by Mariatta, Pradyun Gedam and Manuel Kaufmann
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. :)
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?
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.
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).
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.
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):
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-themeandpypa-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).
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
Reacted by Julien Palard, Juan Luis Cano Rodríguez, Pavithra Eswaramoorthy and Manuel Kaufmann
I'm not able to help with CSS/UI/UX but you have my full support if you need anything docsbuild-scripts side. Once mature enough we can even test things at scale on docs.python.org/dev/.
Hmm... I was thinking about this a bunch today, and a good question came to mind: What do people find good about the existing docs.python.org theme? Not the content, not the fact that it's translated, not the fact that you can search things, not the fact that you can check different versions easily -- just the actual Sphinx theme. What do people like about that?
One potential answer that came to mind was: The collapsing sidebar. So... I've gone ahead and implemented that. And, also, yes, this is very much a prompt to tell me more such things. 😅
I can't really think of anything else personally, and short of sending an email to something like python-ideas, does anyone have any suggestions for how to easily survey a bunch of folks?
I personally don't like it, but I heard of people using it.
any suggestions for how to easily survey a bunch of folks?
Deploy the theme on docs.python.org/dev/ (I can help) and see if someone miss something? I used this strategy a lot at $DAYJOB, we called it WDD for Whine Driven Development: Push to production and raise an ear to catch if someone whines, (works best in big open spaces).
@pradyunsg add a banner/admonition to the docs like the one I've made for pip in the past, for the UX research? Our community/docs folks at Ansible do this as well putting links to surveys there.
What's the status of this issue? With python/python-docs-theme#46 merged, is this “done”? If not, when will it be considered done? Should individual issues be filed for the remaining work?
That was a good attempt, but I think your acting could use some more work. You clearly specified what you were asking, didn't use even a single buzzword and demonstrated far too much understanding of what's actually going on 😆
Reacted by Benjamin Balder Bach and 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко)
I don't think so. When Python documentation came up in a Talk Python to Me podcast episode, one of the things explicitly pointed out was that docs.python.org vs something like https://tailwindcss.com/docs/ are completely different experiences -- with the latter being a lot more pleasing to look at.
If not, when will it be considered done?
I don't think this should be considered done unless we make some progress on improving the overall site design.
Should individual issues be filed for the remaining work?
I don't think we have a clear set of steps for what we want to do here TBH. :)
So... that theme that I've been posting progress updates about here -- I've put the still-very-WIP code for it in a GitHub repository: https://github.com/pradyunsg/lutra/. The theme's own documentation is built using itself, and is available at https://pradyunsg.me/lutra/
Everything about this is very WIP but... hey, it is available publicly under MIT now! :)
PS: If you have feedback on this, use the theme's issue tracker rather than posting comments here.
I'd like to gather folks' inputs/opinions/feedback, to figure out what else needs to be changed/improved about it. To avoid hijacking this issue, I've filed pradyunsg/lutra#22 which is where I'd request folks to post their feedback. I've also added some additional context there, for folks who are interested!
Fair warning: The theme is still WIP, so don't be surprised if you spot things that are borked/non-functional -- please let me know if/when you see that!
Reacted by Manuel Kaufmann and 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко)
Reacted by Manuel Kaufmann and 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко)
Is not having an index page intentional? I think also I'd prefer if languages was spelled out as the word, I was confused by the red glyph in the navigation bar and thought it was a rendering error initially.
Activity
JulienPalard commentedon May 1, 2021
There's two PRs opened on python-docs-theme to modernize the current 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 :
</body>In the other hand, rootrellink is from sphinx, not the theme, so it could by chance just work.
JulienPalard commentedon May 1, 2021
@pradyunsg, quoting you to continue in this relevant thread:
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 commentedon May 1, 2021
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 commentedon May 1, 2021
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 commentedon May 2, 2021
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 commentedon May 2, 2021
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 commentedon May 2, 2021
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 commentedon May 2, 2021
I have no idea how incompatible our language and version switchers are with RTD though.
willingc commentedon May 2, 2021
I believe that RTD has a pretty comprehensive version switcher. We should reach out to Eric Holscher and team.
pradyunsg commentedon May 9, 2021
I just flagged this discussion to @humitos, as he's one of the folks in RTD. :)
humitos commentedon May 10, 2021
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-buildcall.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:
sphinx-hoverxrefextension installedAs 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.pyas 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 commentedon Oct 15, 2021
For info, here's how the current language and version switchers in docs.python.org are working:
<div class="language_switcher_placeholder"></div>so we can play around later.Here are some ideas on how to enhance this: #4
pradyunsg commentedon Oct 15, 2021
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):
My thought process for how things could work is: Lutra builds upon
sphinx-basic-ng(more on this below) and becomes the base theme forpython-docs-themeandpypa-docs-theme, with thepython-docs-themebeing only for Python's documentation. This model means we can get rid of documentation-related templates in CPython's source tree and specialisepython-docs-themeto only be for Python, which may be super useful if we want to add build-time logic (in the Sphinx extension code forpython-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)
(theme dependency tree -- what I'm currently thinking of)
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
JulienPalard commentedon Oct 15, 2021
Haha, he's joking. /me read /me read /me read. Oh he wasn't.
I'm not able to help with CSS/UI/UX but you have my full support if you need anything docsbuild-scripts side. Once mature enough we can even test things at scale on docs.python.org/dev/.
birkenfeld commentedon Oct 16, 2021
Can I just say that I love it?
6 remaining items
pradyunsg commentedon Jan 11, 2022
Hmm... I was thinking about this a bunch today, and a good question came to mind: What do people find good about the existing docs.python.org theme? Not the content, not the fact that it's translated, not the fact that you can search things, not the fact that you can check different versions easily -- just the actual Sphinx theme. What do people like about that?
One potential answer that came to mind was: The collapsing sidebar. So... I've gone ahead and implemented that. And, also, yes, this is very much a prompt to tell me more such things. 😅
I can't really think of anything else personally, and short of sending an email to something like python-ideas, does anyone have any suggestions for how to easily survey a bunch of folks?
JulienPalard commentedon Jan 11, 2022
I personally don't like it, but I heard of people using it.
Deploy the theme on docs.python.org/dev/ (I can help) and see if someone miss something? I used this strategy a lot at $DAYJOB, we called it WDD for Whine Driven Development: Push to production and raise an ear to catch if someone whines, (works best in big open spaces).
webknjaz commentedon Jan 11, 2022
@pradyunsg add a banner/admonition to the docs like the one I've made for pip in the past, for the UX research? Our community/docs folks at Ansible do this as well putting links to surveys there.
JulienPalard commentedon Jan 12, 2022
Oh yes, we do use a "deprecation notice" banner on docs.python.org too, see: https://docs.python.org/2.7/.
pradyunsg commentedon Jan 13, 2022
I'd prefer to instead allow adding a upvote/downvote thing, into a survey platform or whatever -- similar to the bottom of https://squidfunk.github.io/mkdocs-material/getting-started/#with-git or https://www.gatsbyjs.com/docs/quick-start.
Yup! We'll treat that as an "announcement", similar to how Furo does things! :)
encukou commentedon Mar 14, 2022
Hi! Let me play project manager here.
What's the status of this issue? With python/python-docs-theme#46 merged, is this “done”? If not, when will it be considered done? Should individual issues be filed for the remaining work?
CAM-Gerlach commentedon Mar 14, 2022
That was a good attempt, but I think your acting could use some more work. You clearly specified what you were asking, didn't use even a single buzzword and demonstrated far too much understanding of what's actually going on 😆
pradyunsg commentedon Mar 19, 2022
Still needs more work. :P
I don't think so. When Python documentation came up in a Talk Python to Me podcast episode, one of the things explicitly pointed out was that docs.python.org vs something like https://tailwindcss.com/docs/ are completely different experiences -- with the latter being a lot more pleasing to look at.
I don't think this should be considered done unless we make some progress on improving the overall site design.
I don't think we have a clear set of steps for what we want to do here TBH. :)
pradyunsg commentedon Mar 19, 2022
So... that theme that I've been posting progress updates about here -- I've put the still-very-WIP code for it in a GitHub repository: https://github.com/pradyunsg/lutra/. The theme's own documentation is built using itself, and is available at https://pradyunsg.me/lutra/
Everything about this is very WIP but... hey, it is available publicly under MIT now! :)
PS: If you have feedback on this, use the theme's issue tracker rather than posting comments here.
pradyunsg commentedon Jun 6, 2022
For posterity, there was some discussion about the documentation theme in the Python Documentation Community Discord (starting around https://discord.com/channels/935215565872693329/935215566334079058/975795392027447387).
I've gotten Lutra to a point where it's building the Python documentation without crashes and most elements are stylised. Here's a link to CPython's current
mainrendered with Lutra: https://pradyunsg-cpython-lutra-testing.readthedocs.io/en/latest/index.html.I'd like to gather folks' inputs/opinions/feedback, to figure out what else needs to be changed/improved about it. To avoid hijacking this issue, I've filed pradyunsg/lutra#22 which is where I'd request folks to post their feedback. I've also added some additional context there, for folks who are interested!
Fair warning: The theme is still WIP, so don't be surprised if you spot things that are borked/non-functional -- please let me know if/when you see that!
AA-Turner commentedon Jun 6, 2022
Is not having an index page intentional? I think also I'd prefer if languages was spelled out as the word, I was confused by the red glyph in the navigation bar and thought it was a rendering error initially.
Screenshot
A
pradyunsg commentedon Jun 6, 2022
Waiting on the RTD build which will add a description for why that page is empty: pradyunsg/cpython@f41c09b
The red glyph is mostly a placeholder reminder for me, that I have to handle language and version selectors outside of RTD builds.
If there's more to discuss, let's do that over at pradyunsg/lutra#22! :)
anotherk1nd commentedon Jan 16, 2025
Can this be closed now?
hugovk commentedon Jan 17, 2025
python/python-docs-theme#46 has been merged, making the theme responsive, so I suggest we close this, and new issues can be opened for other things.