Base upon the pydata-sphinx-theme

[Cadair]

Infrastructure todo:

• [x] Add a global footer, and reconfigure the book theme article footer (I think we can do this the same way as the header).
• [x] ~Add back copybutton.js (or is there a sphinx extension for that now?)~ - yes: https://github.com/executablebooks/sphinx-copybutton
• [x] Drop the conf.py completely and provide things like the svg path as variables in the package to be imported.
• [x] What is page_url doing when we build the nav bar?
• [x] Deal with RTD switcher at bottom of right sidebar being hidden under the footer.
• [x] The "logo" top left navigates to the wrong url on the local website build.
• [x] Consider if we want to integrate other pydata sphinx theme top navbar items - i.e. search?
• [x] Ensure ndcube's logo still shows up.

Styling:

• [x] Fix always-present scrollbar on the left hand sidebar
• [x] Fix top nav items in sidebar on mobile
• [x] Add more sunpy colours to the light theme (link colours, verbatim etc)
• [x] Dark theme lolz
• [x] Maybe move topnav items to be aligned with the main content rather than left aligned?
• [x] Make the content have a min width rather than be dynamic width?
• [x] Decisions on prev / next arrows (useful for tutorial in sunpy docs? less useful other pages) - can be toggled per-repo.
• [x] Because the sbt article nav is disabled on sunpy.org home page theres no way to get the sidenav to display on mobile.
• [x] sidebar width appears wrong on mobile.
• [x] graphviz graphs and docs.sunpy.org graphic don't work well in dark theme

website todo:

• [x] add back version.js
• [x] fix up landing page
• [x] re-theme our cards extension (can we use sphinx-design for any of this?)
• [x] Deal with weird sidebar configs
• [x] Blog posts are broken
• [ ] sunpy.org cards images are broken on circleci

Possibly post-release:

• [ ] Style the navbar dropdowns the same as the toctree items when in the sidebar.
• [ ] Add a theme config option to disable header bar (for Dash/Zeal)
• [x] Adjust the landing page svg on sunpy docs for dark theme
• [ ] Adjust the coordinates graphviz for dark theme
• [ ] Pygments style

Fixes https://github.com/sunpy/sunpy-sphinx-theme/issues/136 Fixes https://github.com/sunpy/sunpy-sphinx-theme/issues/36 Fixes https://github.com/sunpy/sunpy-sphinx-theme/issues/54 Fixes https://github.com/sunpy/sunpy-sphinx-theme/issues/95 Fixes https://github.com/sunpy/sunpy-sphinx-theme/issues/93 Fixes https://github.com/sunpy/sunpy-sphinx-theme/issues/52 Fixes https://github.com/sunpy/sunpy-sphinx-theme/issues/21 Fixes https://github.com/sunpy/sunpy-sphinx-theme/issues/29 Fixes https://github.com/sunpy/sunpy-sphinx-theme/issues/94

---

So I know for later, I am running the following sphinx-autobuild command to cross-build the sunpy docs on a new theme change:

$ sphinx-autobuild docs/ docs/_build/html/ --re-ignore "docs/api/*" --re-ignore "docs/generated/*" -D plot_gallery=0 -j auto --watch ../sunpy-sphinx-theme/ -a

it assumes you have sunpy/ and sunpy-sphinx-theme/ checked out next to each other, the -a flag to sphinx to write all files every build is needed or it wont overwrite the theme style files.

[Cadair]

pre-commit.ci autofix

[Cadair]

I think this is largely ready for review, at least to find bugs etc.

Before we merge it we are going to need to sort out how we handle a big change like this. I think the rough todo is:

• Write some documentation for the theme.
• Test that the conf.py backwards compatibly holds so that old versions of packages rebuild correctly for the new theme.
• Do an rc and check things in the wild.
• Other stuff??

[nabobalis]

• Write some documentation for the theme.

You mean in the readme or you want a proper docs folder and on RTD?

• Test that the conf.py backwards compatibly holds so that old versions of packages rebuild correctly for the new theme.

We should break this and update the packages. I do not care if 2 year old versions of our packages can not have new docs.

[nabobalis]

The navbar on circleci has not worked out the correct base URL. I am unsure if we need to worry about that or not tho.

It feels like it should work.

[nabobalis]

Probably need to move some content here on the website side.

I assume we also can not do anything about the sidebar?

[Cadair]

• Write some documentation for the theme.

You mean in the readme or you want a proper docs folder and on RTD?

I was thinking a proper RTD setup, mainly as a way of adding yet another test build. I also want to do a little refactoring while seeing how easy it is to adapt this theme for DKIST.

• Test that the conf.py backwards compatibly holds so that old versions of packages rebuild correctly for the new theme.

We should break this and update the packages. I do not care if 2 year old versions of our packages can not have new docs.

I disagree, the auto-rebuild script will rebuild all active versions of all the packages, we want all those to keep working. Doing a bugfix release of every supported branch is not easier than a 10 line conf.py file.

The navbar on circleci has not worked out the correct base URL. I am unsure if we need to worry about that or not tho.

I noticed that right before logging off yesterday, should be fixable.

The About page

How did you even navigate there? :laughing:

[nabobalis]

I was thinking a proper RTD setup, mainly as a way of adding yet another test build. I also want to do a little refactoring while seeing how easy it is to adapt this theme for DKIST.

Hmm, that was what the test package was about but maybe that can be rolled into the theme itself instead? But yeah, that makes more sense than just having the test package.

I disagree, the auto-rebuild script will rebuild all active versions of all the packages, we want all those to keep working. Doing a bugfix release of every supported branch is not easier than a 10 line conf.py file.

We should have less versions to support plus we have not done a proper release of several AF packages recently, this forces us to do it.

Break the theme, fix the packages.

The About page

How did you even navigate there? 😆

I clicked on the about on the sidebar.

[Cadair]

Break the theme, fix the packages.

I still think we should keep it for a while, it's hardly the worst thing in the world, and it makes it a lot less faffy to roll out rather than having to do a release with an rc then adjust later etc.

I clicked on the about on the sidebar.

I think I have fixed this now, with a little re-arrangement of the content on the website. The "SunPy" link on the navbar is still wrong on the website though (it links to the current page).

[nabobalis]

Curious thing I came across

The url is on circle but when I open the sidebar and use the link it takes me to the main SunPy.org website.

I can't replicate this on my computer.

[nabobalis]

Also should this be there on the main docs sidebar?

[Cadair]

Thanks for the testing @nabobalis

The url is on circle but when I open the sidebar and use the link it takes me to the main SunPy.org website.

Looks like you are on the sunpy docs build, that links to sunpy.org not the other circle-ci build. We would have to build all the pages in one job for that cross-linking to work.

Also should this be there on the main docs sidebar?

I assume you mean the topnav items. Yes, it's where pydata-sphinx-theme puts the topnav when it moves it out of the top bar. The code's custom but it matches the default behaviour.

[nabobalis]

Thanks @Cadair, it was one hell of a workout.