Migrate documentation to new unified astropy sphinx theme - #19206

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 instructions for rebase and squash.
• 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?
• 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.

Is this worthy of a changelog?

I'm going to optimistically milestone this for 8.0 and then send @astrofrog some pizza or something.

I'll be in touch about my preferred toppings!

I think he likes cash stuffed crust.

Wow look at how orange it is: https://astropy--19206.org.readthedocs.build/en/19206/

@eteq should be happy now.

FWIW we did not include a change log when we switched theme the last time

• Use pydata-sphinx-theme #14867

I added some links on the original post as this PR would naturally close a few issues (yay).

Any chance you want to address #15112 also while you are at it?

@Cadair - generally speaking this looks great and has a nice feel.

I do wonder a bit about the bright orange links, which on some pages seem a bit much, especially on the main user docs index (https://astropy--19206.org.readthedocs.build/en/19206/index_user_docs.html). Is this break from the standard scientific Python docs theme driven by a broader web design principle?

On the light or dark theme?

Is this break from the standard scientific Python docs theme driven by a broader web design principle?

I picked the colours so they were astropy themed. They are the ones from the logo. They can be tweaked but you do need to maintain a high contrast ratio for accessibility.

Also, we shouldn't hold this PR up unnecessarily on colour choices. We can repaint the bikeshed to our hearts content over on the theme repo.

The main objectives here are the unified search and the unified navigation bar over all astropy documentation sites.

On the light or dark theme?

Both, and the dark theme it is especially bright and jarring.

we shouldn't hold this PR up unnecessarily on colour choices. We can repaint the bikeshed to our hearts content over on the theme repo.

Colour choices matter quite significantly and I would not call this bikeshedding. As you note the intent of this PR is unified infrastructure and theme, but right now this has the consequence of making a major and completely non-standard "interface change" to a widely used astropy page. None of the other major projects deviate from normal blue-tinted links in their web pages.

They can be tweaked but you do need to maintain a high contrast ratio for accessibility.

That might be controversial. I asked gemini "is orange a good color for web page links?"

Orange is an excellent, high-visibility color for call-to-action (CTA) buttons or specific, attention-grabbing links, as it combines energy with warmth to boost conversions. However, it is generally poor for standard body text links, as it lacks the universal recognition of blue and can pose accessibility challenges.

You can take that or leave it, but none of us are web design experts so I would tend to defer to the default non-controversial colors in the standard theme. So that would imply changing the astropy.org theme colors rather than the docs.astropy.org theme colors to be fully unified.

I think there's some context missing here. When I say we shouldn't hold up this PR, I mean because the colours are not defined in this repo (they are in astropy-sphinx-theme) and I don't want to hold up the 8.0 release process. We can release a new version of astropy-sphinx-theme and rebuild the RTD builds and the colours will be updated with no PRs to this repo at all. Also any changes to the theme will be reflected in all repos, website included.

I don't actually care what the colours for the theme are, I asked for feedback on the theme pushing 4 months ago. I've opened a PR which resets the link colours in the body of the pages to the pydata-sphinx-theme colours here: astropy/astropy-sphinx-theme#58

@Cadair - thanks for the clarification, that makes sense. So I would endorse merging this PR contingent upon agreement (in principle) to change the astropy-sphinx-theme prior to the 8.0 release.

I'll confess that the unusual orange links in the astropy.org site had not previously caught my eye. This is partly because some of the links on the first landing page are actually in the call-to-action category, and partly because I just don't use that site nearly as much and it simply escaped my attention.

I do care about colors and also believe that adhering to almost universally-adopted web standards is important.

contingent upon agreement (in principle) to change the astropy-sphinx-theme

I have no issues with changing things, but basically so far only ~4 people have reviewed the theme. 🤷

Maybe it is better to re-milestone this to v8.1 so we have time do make such discussions and not rush things into production?

It's already in production, ccdproc just merged it, the website has merged it. We can change the theme settings without any issues. I see no reason to delay this, but you all do what you want.

And to be explicit, I am happy to agree to merging the theme PR to update the link colors.

👍 on merging now for 8.0.