Stable version as default in docs

[leonlan]

Is your feature request related to a problem? Please describe

Most users install PyVRP through PyPI and so they use the stable version. However, www.pyvrp.org shows the documentation for the latest development version by default, possibly confusing users when they find features in the docs that aren't released yet.

Describe the solution you'd like

• www.pyvrp.org should default to the stable version of PyVRP.
• www.pyvrp.org/dev should default to the latest development version of PyVRP.

[N-Wouda]

Related: #273 (but that issue covers a whole bunch of things).

[leonlan]

I'll pick this up ASAP. We're getting many questions about stuff not working because of this 😅

[N-Wouda]

We also have the "older" docs hosted in this repository: https://github.com/PyVRP/PyVRP.github.io. Those are available at https://pyvrp.github.io/v0.7.0/, and so on. It'd be nice if we can somehow merge all that together so that:

• pyvrp.org -> latest stable
• pyvrp.org/dev -> latest build on main
• pyvrp.org/v<version> -> docs associated with version <version>

I don't really know how to do this. I do know statsmodels has things set up exactly this way. Maybe we can borrow some of their setup for our own purposes?

[N-Wouda]

I'm assigning this for 0.9.0, since we really ought to solve this ASAP.

[leonlan]

I'm looking into how statsmodels does it for the next hour and will make notes in this comment.

• Dev should be be built continuously.
  • Instead of doing uploading the built docs to PyVRP, we can upload it do PyVRP.github.io.
• Stable can be built once after a release and put in PyVRP.github.io.
  • But dumping all HTML content of the stable version in the root is ugly. How to avoid that?
  • Maybe we should have pyvrp.org redirect to pyvrp.org/stable or use an alias.
• To get pyvrp.org/v<version> is easy: we add the pyvrp.org domain to PyVRP.github.io and rename the URLs in conf.py's version_info.
• The version dropdown should probably be hardcoded in conf.py or we have to mess around with version.json files like statsmodels has right now.
• Statsmodels
  • Doc build worfklow: https://github.com/statsmodels/statsmodels/actions/runs/8324011615/workflow
  • Doc build scripts: https://github.com/statsmodels/statsmodels/tree/main/tools/ci
  • https://github.com/statsmodels/statsmodels.github.io
  • https://cpina.github.io/push-to-another-repository-docs/index.html

[N-Wouda]

Alright I had hoped to work on this today, but the devcontainer stuff took a little longer and now it's getting late. There's always tomorrow :).

[N-Wouda]

I don't want this to block a release of 0.9.0, but I'll try to finish it in the coming week.

[N-Wouda]

Possibly interesting: https://github.com/jimporter/mike