Switch between docs versions not built on readthedocs

[HealthyPear]

This is more of a question/curiosity than an actual issue.

In your docs example you show what happens for your repository, whose documentation is stored on readthedocs where each version (at least the ones one decides to activate) is built separately.

If a project doesn't use readthedocs (for example GitHub Pages or the equivalent for GitLab), I guess there is always the need to have something that builds each version and deploys the associated documentation to a well defined URL that then is defined in the switcher.json file.

What would be some nice implementations of this?
Do you know any open-source project that falls into this use-case and implemented something that works?

[damianavila]

It seems Numpy is build the docs as Circle CI jobs: https://github.com/numpy/numpy/blob/main/.circleci/config.yml
@tupui, can you confirm and drop some more info if that is the case? Thanks!

[tupui]

Yes NumPy and SciPy (which I know better since I've done the switcher here) are both using CircleCI. And CircleCI is building on each PRs and allow to store artifacts (so the website).

To answer the question: I am actually changing the version name to match the PR number. It does not match any version in the json but still prints the version in the selector and use default CSS. It has the same effect as you have with the warning on RTD saying this doc is for a PR.

I also have some specific CSS for the colors of current, old and dev versions (soon we can have CSS for the default since we merged my PR here, next version then). Not much more. You can have a look at the config and CSS of SciPy. Let me know if you have specific questions 😃

[12rambau]

@HealthyPear is @tupui answer solved your issue ?

[HealthyPear]

oh right sorry @12rambau , I got lost with other work and I totally forgot about this issue that was months ago....

I guess circle CI is OK, but I was referring to an "artisanal" solution, without using external software: meaning, I have a server and I deploy there, so I need something that checks out e.g. each tagged release and stores the build docs in a directory tree which complies with what this sphinx theme expects.

But of course, getting a list of PRs might be more complicated...

[12rambau]

I converted it to a discussion in case someone wants to share a building method

[prjemian]

FWIW, I started a template project to demonstrate one way to do this. Straightforward implementation of the version switcher per the docs. Plus:

• color the dropdown items using custom CSS, as suggested
• use the switcher.json file in the main repo branch docs
• keep the cache of previous documentation versions in the gh-pages branch
• capture docs for each new tag
  • which means that gh-pages branch grows with each new tag
  • OK for small projects, but large projects could have ~100MB of content with each version (the images) so not a general technique
  • welcoming suggestions on how to do this better
• CI workflow to combine new docs with existing cache

[OriolAbril]

If it helps, my blog is hosted on github pages and uses the switcher to have two languages. The look is quite different but it is built with sphinx using a custom theme that depends on pydata-sphinx-theme.

Source (for sphinx): https://github.com/OriolAbril/oriol_unraveled
Deployed source: https://github.com/OriolAbril/oriol_unraveled/tree/sphinx-build
Deployed (as website): https://oriolabrilpla.cat/en/