Thank you for your contribution to Astropy! 🌌 This checklist is meant to remind the package maintainers who will review this pull request of some common things to look for.

• Do the proposed changes actually accomplish desired goals?
• Do the proposed changes follow the Astropy coding guidelines?
• Are tests added/updated as required? If so, do they follow the Astropy testing guidelines?
• Are docs added/updated as required? If so, do they follow the Astropy documentation guidelines?
• Is rebase and/or squash necessary? If so, please provide the author with appropriate instructions. Also see "When to rebase and squash commits".
• Did the CI pass? If no, are the failures related? If you need to run daily and weekly cron jobs as part of the PR, please apply the "Extra CI" label. Codestyle issues can be fixed by the bot.
• Is a change log needed? If yes, did the change log check pass? If no, add the "no-changelog-entry-needed" label. If this is a manual backport, use the "skip-changelog-checks" label unless special changelog handling is necessary.
• Is this a big PR that makes a "What's new?" entry worthwhile and if so, is (1) a "what's new" entry included in this PR and (2) the "whatsnew-needed" label applied?
• Is a milestone set? Milestone must be set but we cannot check for it on Actions; do not let the green checkmark fool you.
• At the time of adding the milestone, if the milestone set requires a backport to release branch(es), apply the appropriate "backport-X.Y.x" label(s) before merge.

👋 Thank you for your draft pull request! Do you know that you can use [ci skip] or [skip ci] in your commit messages to skip running continuous integration tests until you are ready?

pre-commit.ci autofix

Thanks for all your help, @drammock ! If you want, I can add you as co-author on the second commit. Just have to give me the info I can link to your GitHub account (Name <email>).

Thanks for all your help, @drammock ! If you want, I can add you as co-author on the second commit. Just have to give me the info I can link to your GitHub account (Name <email>).

Co-authored-by: Daniel McCloy <dan@mccloy.info>

Thanks! Probably the only time I'll know enough to contribute to astropy 😅

Thanks for working on that @pllim :)
There is a thing that is missing compared to the old PR (maybe due to the toctree tweaks): the theme can show the toctree of the subpackage when browsing a subpage, in the left bar, e.g.

This is very useful to discover other subsections, but it's not showing up in the new version.
old: https://astropy--14477.org.readthedocs.build/en/14477/user/units/quantity.html
new: https://astropy--14867.org.readthedocs.build/en/14867/units/quantity.html

That must be because of the new levels of toctrees. I think the navigation between subsections/subpackages with the sidebar was clearer in the old version.
Also,

• not sure if we need the sidebar in the index page, it duplicates the content of the page
• a lot of the space in the index page is taken by less important things (e.g. the Development section) whereas the most important (the list of subpackages) is hidden.

I think the navigation between subsections/subpackages with the sidebar was clearer in the old version

I struggle with this one because it is tough to retain the old behavior without moving the files around (as you did, but the it got conflicts very quickly). If we were to do it your way, this PR will have to get merged really fast after I make move the files. What do you think? Is there some other sidebar CSS trick or something that I need to know here?

a lot of the space in the index page is taken by less important things (e.g. the Development section) whereas the most important (the list of subpackages) is hidden

Same problem as above. A side effect of my trying not to move files around. So I guess I'll either have to move files like you did in #14477 or figure out a clever way to lay out the TOC.

not sure if we need the sidebar in the index page

The original theme doesn't include it. I actually included this one because on my small laptop screen, I had to scroll through a lot to get to the bottom of the index page and found discovering via sidebar easier. But now that I am back on normal PC monitor, I see your point. I can remove it.

Probably the only time I'll know enough to contribute to astropy

Don't be silly, @drammock ! 😸

My initial review of the output is that this looks fantastic. I strongly endorse moving forward with this effort!

I struggle with this one because it is tough to retain the old behavior without moving the files around (as you did, but the it got conflicts very quickly). If we were to do it your way, this PR will have to get merged really fast after I make move the files. What do you think?

I think the most important is that the docs are well organized and easy to browse, for users. So if we need to move files for that and we don't have a good alternative, then we just need to do it. If there is an agreement then we can do that quickly enough to avoid conflicts I guess.

@saimn , I think I figured it out. It was a matter of where to put the headings and how many levels of sub-headings to expose in TOC. A little tricky but I think the layout now closely matches what you came up with in #14477 without moving files around, at least when I built it locally. Let's see if RTD agrees.

Looking forward to this quite a bit -- thanks to everyone who made it happen!

In general I'm liking this now, but one question: is the intent to keep all the old docs as they were, and switch to this on dev (and then presumably it's "offical" in the next release)? Or to try to push the theme back to the older versions as well?

I'm in favor of it "from now on" rather than trying to change any older versions, which I think is the intent, but just confirming.

Or to try to push the theme back to the older versions as well?

I have zero intention nor time to try to backport this. So, this new theme won't be "released" until v6 is out by the end of 2023.

Ok awesome, then I like where it is now! I still have some color quibbles (I we should use "Astropy orange" in some places) but I don't think that needs to block this PR, it can be a follow-up PR once this is in.

Thanks! For the record: 3/5 CoCo members approved (I have to abstain and Derek is on vacation).

It failed with a warning that is unrelated (numpy/numpy.org#664) but it does block RTD from building. 😭

WARNING: The following HTTPError has occurred fetching https://numpy.org/doc/stable//: 404 (Not Found)

RTD passed but didn't report back. I am just gonna merge manually. Thanks!

Thanks for getting this done! I do agree to some extent with #14867 (comment), although having both Notes and lengthy Warnings is a particularly disadvantageous example, and I also find the box rendering in the new docs much more pleasant on the eyes.
Section headings font sizes indeed seem quite excessive, so there probably is some fine-tuning to be done in the follow-up.

Most section heading levels are inherited from the old theme, so I think modifying the CSS rather than changing the RST would probably be less disruptive. I will open issue (#15112).