Repository navigation
DOC: pydata sphinx theme #11520
Description
Description
I would propose to use the PyData Sphinx Theme for the documentation. This theme is used by most Python tools from NumFOCUS. Examples include: NumPy, Pandas, SciPy (devdocs) and also Matplotlib (WIP).
Let me know if this is something which could interest you. I did the work for SciPy and can do a PR here.
Activity
pllim commentedon Apr 12, 2021
I guess that this actually would apply to all the repos in the Project? Or is applying it in core lib here sufficient?
adrn commentedon Apr 12, 2021
This is an interesting idea and worth discussing! I assigned @embray to respond because, funnily enough, we were just discussing this last week. As mentioned above, here is the NumPy documentation as an example.
pllim commentedon Apr 12, 2021
While we're talking about themes, how about dark mode? 😉
embray commentedon Apr 22, 2021
I was just checking the Docs label to see if there was already an issue for this opened, and was otherwise going to open it.
I'm preparing a meta-issue of documentation reorganization issues, and this will be part of it (since, based on my existing experiments with the PyData theme, for it to work well with the Astropy docs they'll need to be reorganized a bit anyways).
tupui commentedon Apr 22, 2021
OK sure I will let you do it @embray if you prefer. (I did not start yet as I was waiting for the go here).
embray commentedon Apr 22, 2021
Other related issues are #9277 as well as #8320. This might be a good opportunity to try to unify the nav menus of the main Astropy website and the documentation page to make them a little more cohesive.
I wouldn't necessarily make them exactly one-in-the-same, but having links like "Affiliated Packages" on the docs would, at a minimum, be useful, I think?
embray commentedon Apr 22, 2021
Thanks @tupui perhaps we can work together on it since you already have familiarity with the theme.
I already did a quick experiment earlier with enabling the pydata theme and the results were...not spectacular:
Of course, this seems to be mostly related to how the nav bar items are being generated. It's probably a simple fix to make it into something clean and elegant like on Numpy and Pandas.
One thing that might differ is that the way Astropy organizes its docs there is no one single "API Reference" index page for the Astropy docs. Most of the user documentation is organized along the lines of sub-packages, with API references for each sub-package on each sub-package-specific page. This was a decision that was made in the very early days of the package, and I think it wasn't a bad one.
It looks like for the new SciPy docs you added a top-level API reference page, and I could see something like that being useful for Astropy. It also has some front text that's somewhat similar to what we have on this Importing Astropy page.
I'm going to open a more general ticket about doc reorganization that I think we would want to go hand-in-hand with any theme updates.
tupui commentedon Apr 22, 2021
I would be glad to help. Just ping me when you want me to look into something then.
ps: for the dark mode, they is an issue on the theme side. It's one of the big plus of having a common them between packages, we will be able to share things between us 😃
tupui commentedon Jun 23, 2021
@embray any update here?
embray commentedon Jun 29, 2021
@tupui Not yet I'm afraid. I've been focusing more for now on getting the developer docs restructured (#11840) which I kind of see as a prerequisite to this. But in fact since I've at least started the task, I could probably play around with this again on top of that branch. Thanks for checking in on it.
tupui commentedon Jun 29, 2021
@embray sure no problem. Again let me know if I can help as I did this for SciPy it should not be a big deal.
pllim commentedon May 25, 2023
@tupui , after 2 years, @saimn did an early POC at #14477 and I wrapped it up at #14867 during the Scientific Python Developers Summit 2023. 🐱
Many thanks to @drammock and @ksunden for their help!