Add version switcher to Sphinx docs

[santisoler]

Summary

Add a version switcher to the navbar of the docs, using the built in one in PyData Sphinx theme. Point to the experimental versions.json file located in doctest.simpeg.xyz that should serve the files in simpeg/simpeg-doctest. Add experimental staged to Azure Pipelines that pushes docs to the simpeg-doctest repository. One is triggered nightly and deploys the latest docs in main to the dev branch in simpeg-doctest and updates the dev submodule in gh-pages. The other one is triggered after a release and pushes the new version of the docs to gh-pages branch in simpeg-doctest onto a new folder, while also updating the latest link.

PR Checklist

• If this is a work in progress PR, set as a Draft PR
• Linted my code according to the style guides.
• Added tests to verify changes to the code.
• Added necessary documentation to any new functions/classes following the
  expect style.
• Marked as ready for review (if this is was a draft PR), and converted
  to a Pull Request
• Tagged @simpeg/simpeg-developers when ready for review.

Reference issue

What does this implement/fix?

Additional information

TODO:

• Add task in the release checklist (Add new Issue template for making a release #1410) to update the versions.json file
• Build and deploy docs after push to main. Docs should be pushed to replace the content of the dev folder where the docs are being hosted.
• Add a checkout step that also syncs tags: see Fix links to source code in documentation pages #1444 for reference

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 82.33%. Comparing base (dd7cc94) to head (8e85fad).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1428   +/-   ##
=======================================
  Coverage   82.33%   82.33%           
=======================================
  Files         171      171           
  Lines       26019    26019           
=======================================
  Hits        21422    21422           
  Misses       4597     4597           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[jcapriot]

Since this is changing the format of the documentation page (and I imagine you might start seeing text wrapping soon), I think it's also appropriate to consider a few things:

• Do we really need the youtube link on the navbar on every page, or is a link on the main page sufficient?
• Is a link back to simpeg.xyz in the center navbar useful? (Probably not)
• Is the contact link to Mattermost in the center navbar useful? (Definitely leave the icon link)
• Should we move the search bar to the left menu (i.e. https://numpy.org/doc/stable/index.html)?
• Consider renaming the items in the center with one word aliases (consider these as suggestions)?
  • API Reference -> API
  • Release Notes -> changelog
  • User Tutorials -> Learn

[ghwilliams]

Great.
It is a headache when the documentation is not synchronized with the source code. Many times, I got lost trying to reproduce an example from an open-source code just because the documentation was created for an old, outdated version. If the documentation is tested against the corresponding version of the software and kept recorded together with each release, it will make learning SimPEG a much more enjoyable experience.

[santisoler]

@jcapriot would you like to take a look at this? Specially to the scripts for deploying the docs.

I added those to experiment and see if the setup works properly on simpeg-doctest. If we are happy with it, at some point we could update the pipelines and switch them to simpeg-docs and make it the official deployment process.

Also, I was considering hosting the docs in a gh-pages orphan branch in this repo, instead of having a separate repo for them. That would also ease the process of implementing this new workflow: we can just have these new deployment staged pushing to gh-pages and then flip the switch in GitHub Pages configuration. What do you think?

[jcapriot]

Hey @santisoler in general the azure scripts look good, However, do you know if there's a way to serve the doc versions from different branches? (I don't think there's a way in github pages, but there could be something else.)

My thought is to avoid doing the git-clone on the entire documentation website (as it will continually get larger and larger with each release). Instead just commit it's own documentation to a specific branch.

[jcapriot]

Hey @santisoler in general the azure scripts look good, However, do you know if there's a way to serve the doc versions from different branches? (I don't think there's a way in github pages, but there could be something else.)

My thought is to avoid doing the git-clone on the entire documentation website (as it will continually get larger and larger with each release). Instead just commit it's own documentation to a specific branch.

Maybe through using git's submodules with github pages might work...

[santisoler]

I think one can only serve one GH page per repo. Basically, we can only configure GH Pages on a single branch.

While reading your first comment I thought the same: git submodules. But I'm not sure if GH Pages follow the submodules when "generating" the Pages. Every time we push a change to a branch that is serving a GH Page, an Action triggers that "generates the update". I think it basically checks if it needs to run Jekyll or not, and then make the html files available through their webserver. I'm not sure if in that process they also follow all submodules and include those html files.

[santisoler]

That makes sense. I forgot we need to update the submodules as well.

Regarding your proposal, I think it would be better to have versions in their own branches. Mainly because in case we need to apply changes to old docs (change analytics, add a banner, etc), it would be a lot easier than trying to insert commits in the history of the single dev branch.

[santisoler]

I'm rethinking the deployment process. I think having the dev docs in a separate branch is great to avoid a commit history that will grow to large. But the documentation for releases ideally won't change in time. So having all the tagged docs in separate branches makes the process more complex without adding any benefit.

So, what if we keep the dev docs in the dev branch, update the submodule in the gh-pages branch, but commit the release docs to folders in the same gh-pages branch?

[santisoler]

I'm merging this one. I'm quite happy with the setup. It's still experimental so I'll have to open another PR to update the repo where docs should be pushed and the location of the versions.json file before making this the default way to deploy our docs. In order to check that the new pipeline works properly, I need to try it out. Hope everything works smoothly (famous last words) 🤞🏼