Rewrite to a sphinx project and use unified theme #698

Cadair · 2026-01-19T16:30:57Z

You can see a preview of this here: https://astropy-org-test.readthedocs.io/ (where the search works) and also in the circle ci build artifacts.

Fun things to checkout:

light and dark themes
the search!!

I think this is now ready for review, but please confine review to the diff in this PR. i.e. not the theme which should be reviewed here: astropy/astropy-sphinx-theme#48

HTML Pages left to port:

Todo before merge:

Find someone with power to move the astropy.org domain to RTD
Add back Google Analytics, and start a discussion somewhere about improvements later
Merge theme PR and release astropy-sphinx-theme

Other potential improvements:

Use intersphinx for all links to core documentation
See if we can generate a dark theme variant of the home page background

Cadair · 2026-01-19T16:57:43Z

I'll keep a list of things I think we could tidy up here as I go along:

We should get rid of all the affiliated package javascript and have sphinx just do all the page gen on build. Then cronjob the site to rebuild each day or week or something.
The Copy bibtex js on the citation page inlines all the bibtex which is just horrible, we should have sphinx read that in from somewhere sane. What is the canonical source of the citation bibtex?
The javascript for the team page should all be removed and replaced with build-time Python code.

pllim · 2026-01-20T18:55:21Z

You will have to pull this change in too after it is merged. FYI

Filter out astropy core package from pyOpenSci Affiliated listing #699

Cadair · 2026-01-21T14:35:47Z

@astropy/astropy-website-maintainers This is now ready for review.

Cadair · 2026-01-21T14:42:54Z

requirements.txt

+sphinx
+myst-parser
+sphinx-design
+astropy-sphinx-theme@git+https://github.com/Cadair/astropy-sphinx-theme@sunpy-astropy-theme


We should probably cut a release of astropy-sphinx-theme before merging this PR 😉

Can you pls cross link PR from that branch here for future reference? Thanks!

It's in the PR description above.

Oh right, nevermind. We cannot merge until this is resolved. I better block merge given the approval.

pllim · 2026-01-21T14:54:13Z

This is now ready for review

Shouldn't I wait for you to resolve #698 (comment) first?

Cadair · 2026-01-21T14:56:44Z

This is now ready for review

Shouldn't I wait for you to resolve #698 (comment) first?

No, I don't think so. This PR is not about the theme it's about rewriting the astropy.org site to use sphinx. Comments about the theme should go on the theme PR.

hamogu · 2026-01-21T16:22:00Z

Now for the record: I'm not a maintainer of this repro because I have deep experience with web development, it's because we used to manually update the list of affiliated packages in this repro and I was the affiliated package editor at the time (and are again now, though we know how've a difference mechanism).
@eteq is the person who usually reviews changes like this.

That said, I'll have a look as soon as I can.

hamogu

Most of the changes are pretty straightforward changes for html->rst. I'm not saying that to diminish @Cadair 's work (I know it's still a lot of work to do that, but it's not conceptually hard), just to say that the review is basically "it works" and there is no need to review every changed line, because we would not want to include any changes in the wording of individual pages here anyway.
Otherwise, it's a pretty standard setup and I see no problems with it.

hamogu · 2026-01-21T16:28:22Z

_static/js/functions.js

+// Quirk to note: the jQuery.getJSON function fails if you open this locally
+// with Chrome, because Chrome thinks local JSON files are unsafe for some
+// reason.  Use basically any other modern browser, or it works fine if its
+// actually on the web server even with chrome.


Not really important here, since this is just a comment anyway, but I think most modern browsers now refuse to load any local file for security - for testing locally you'll a local web server running for all or most of them.

yeah this comment is pretty old 😆

I'd like to purge this entire file of js if I have the time.

pllim · 2026-01-22T22:33:50Z

You have to resolve conflict to pick up #699 . Thanks!

Cadair · 2026-01-27T13:44:18Z

Merged in main

pllim · 2026-01-27T15:10:30Z

Hmm something is wrong.

Cadair · 2026-01-27T15:13:43Z

Looks like that's a circleci problem, the way that circleci previews somethings doesn't really work properly. If you look at the RTD preview it seems to work.

pllim · 2026-01-27T15:15:40Z

Thanks for the clarification. I hope you are right...

pllim · 2026-01-27T15:16:32Z

So this is good to merge or are we waiting on something else?

pllim · 2026-01-27T15:17:20Z

.circleci/config.yml

+
      - store_artifacts:
-          path: /root/project
+          path: /home/circleci/project/_build/html


You say we would use RTD preview going forward, right? Do we need this?

Arguably not, the main reason I added it was because it was already configured.

I do find that it's nice to have a "real" CI platform checking the build works in addition to RTD however.

But... #698 (comment)

pllim · 2026-01-27T15:18:13Z

exts/rawfiles.py

Can you please add comment to explain what this is for, for future reference?

pllim

Also... Don't we also use some sort of banner mechanism here that "talks" with astropy cord RTD, like when we announced the 10k citation stuff. Would that still work?

pllim · 2026-01-27T15:19:07Z

requirements.txt

+sphinx
+myst-parser
+sphinx-design
+astropy-sphinx-theme@git+https://github.com/Cadair/astropy-sphinx-theme@sunpy-astropy-theme


Oh right, nevermind. We cannot merge until this is resolved. I better block merge given the approval.

Cadair · 2026-01-27T15:20:28Z

So this is good to merge or are we waiting on something else?

There's a todo list in the OP, but mostly it's blocked on people reviewing / approving / arguing about colours on the theme PR.

pllim

Waiting for sunpy theme release

Cadair · 2026-01-27T15:21:05Z

Also... Don't we also use some sort of banner mechanism here that "talks" with astropy cord RTD, like when we announced the 10k citation stuff. Would that still work?

Yes, but I should actually make this site display the banner if it's active!

Cadair · 2026-01-27T15:21:54Z

Oh the other reason this shouldn't be merged at the moment is that it would break astropy.org in its current state. We need to figure out how to do the RTD migration, which needs someone to make (adopt?) the RTD project with an official hat on, and then to know who has the DNS power.

pllim · 2026-01-27T15:23:25Z

RTD migration

I have the power if CoCo7 let me.

DNS power

You have to hunt down @eteq

Cadair added 5 commits January 19, 2026 16:26

TMP: Homepage

f99df2c

TMP: Acknoledge

a26e0ab

TMP: Add in affiliated

b078d38

TMP: Add CoC Pages

aea15a5

TMP: Announcement Banner

c4cf978

Cadair force-pushed the unified-theme-rewrite branch from 4b2fc98 to af49c3f Compare January 19, 2026 16:49

Cadair force-pushed the unified-theme-rewrite branch from cfe1821 to d7ee958 Compare January 19, 2026 20:05

Cadair added 7 commits January 20, 2026 15:00

TMP: About

0509c7a

TMP: help

a7b4391

TMP: history

8645715

TMP: team

57cdd1d

TMP: Contributing

aa0b648

TMP: 10k citations

95ddcea

TMP: announcements

3c1bb51

Cadair force-pushed the unified-theme-rewrite branch from cf5fe56 to 3c1bb51 Compare January 20, 2026 15:00

Cadair added 2 commits January 20, 2026 17:01

add back Python helpers

f93cb03

Some other cleanup

5781303

Cadair force-pushed the unified-theme-rewrite branch from 18ebffe to d351274 Compare January 20, 2026 17:13

Attempt to fix circlci

d4640ba

Cadair force-pushed the unified-theme-rewrite branch from d351274 to d4640ba Compare January 20, 2026 17:17

This comment was marked as outdated.

Sign in to view

Cadair marked this pull request as ready for review January 20, 2026 17:20

Cadair changed the title ~~WIP: Rewrite to a sphinx project and use unified theme~~ Rewrite to a sphinx project and use unified theme Jan 20, 2026

Cadair mentioned this pull request Jan 20, 2026

Add substitutions to credits.rst for astropy.org site astropy/astropy#19192

Merged

1 task

Cadair added 4 commits January 20, 2026 20:47

Update .gitignore

37a7497

Use theme in new home

7731cb2

Remove now redundant subs

0da3980

fix artifact path

4c50f43

Cadair commented Jan 21, 2026

View reviewed changes

Cadair mentioned this pull request Jan 21, 2026

Tracking Issue: Unified Astropy Sphinx Theme Migration astropy/astropy-project#522

Open

hamogu approved these changes Jan 21, 2026

View reviewed changes

Merge remote-tracking branch 'upstream/main' into unified-theme-rewrite

b122766

pllim reviewed Jan 27, 2026

View reviewed changes

exts/rawfiles.py

Copy link

Member

pllim Jan 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you please add comment to explain what this is for, for future reference?

pllim reviewed Jan 27, 2026

View reviewed changes

pllim requested changes Jan 27, 2026

View reviewed changes

Uh oh!

Rewrite to a sphinx project and use unified theme #698

Are you sure you want to change the base?

Rewrite to a sphinx project and use unified theme #698

Uh oh!

Conversation

Cadair commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Cadair commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

pllim commented Jan 20, 2026

Uh oh!

Cadair commented Jan 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pllim commented Jan 21, 2026

Uh oh!

Cadair commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hamogu commented Jan 21, 2026

Uh oh!

hamogu left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pllim commented Jan 22, 2026

Uh oh!

Cadair commented Jan 27, 2026

Uh oh!

pllim commented Jan 27, 2026

Uh oh!

Cadair commented Jan 27, 2026

Uh oh!

pllim commented Jan 27, 2026

Uh oh!

pllim commented Jan 27, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pllim left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Cadair commented Jan 27, 2026

Uh oh!

pllim left a comment

Choose a reason for hiding this comment

Uh oh!

Cadair commented Jan 27, 2026

Uh oh!

Cadair commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pllim commented Jan 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Cadair commented Jan 19, 2026 •

edited

Loading

Cadair commented Jan 19, 2026 •

edited

Loading

Cadair commented Jan 21, 2026 •

edited

Loading

Cadair commented Jan 27, 2026 •

edited

Loading