PR 1/2: Add versioned docs

[till-m]

Fix #504

Demo: https://till-m.github.io/BayesianOptimization/

This adds a version dropdown to our docs page. In the future, any new release will be added to this version dropdown automatically. Similarly, it will keep an updated version of the master docs.

I had to switch to sphinx-immaterial to get this to work. I’ve also cleaned up the docs a bit and made everything look nicer (imo).

I've also trimmed the README significantly.

How does it work?

There’s a workflow that runs on push (master), pull request and release. This workflow does a number of things.

1) build-docs-and-publish

1. It builds the docs (to use but also to check whether they actually build).
2. It determines the current state of the git ref and sets a target variable accordingly.
   1. If running on master, set target to master
   2. If running on a release, set target to release version
   3. If running due to PR, set target to empty string
3. If the target is not empty string, it deploys the html folder of the built docs to gh-pages/<target>. It overwrites anything in <target> but ignores any other content in gh-pages

2) Update docs versions JSON

Only runs if the target is not empty

1. Clones the gh-pages branch and reads out the folders within (ignoring anything starting with .)
2. Reads out the folder names, determines which are referring to versions and which not.
3. Finds the maximum version
4. Generates a JSON object encoding the present folders/version and the maximum version
5. Pushes that JSON file to the gh-pages (ignoring any other files in the branch).

When you open the docs page, the landing page reads out the versions.json and redirects you to stable. If there is no version tagged stable, it will redirect to master.

On merging this

Requires a sister PR to be merged first, prepping the gh-pages branch: #510

I’ve purged the gh-pages branch and added docs for the v1.5.1 release. This way I could a) test the publish workflow, b) ensure that there is a stable version present, c) make persistent docs for v.1.5.1 and d) have a more functional demo.

Credit

Based on github.com/brechtm/rinohtype's workflow.

[till-m]

@phi-friday I will put your PRs on hold until this is sorted out, because any merge conflict on gh-pages would be horrible to resolve. My apologies.

[phi-friday]

@phi-friday I will put your PRs on hold until this is sorted out, because any merge conflict on gh-pages would be horrible to resolve. My apologies.

I'm sorry I can't help you with that, I'm not familiar with the documentation.

I looked at the link you showed as an example and it seems to be better in accessibility, like dark mode support and clipboard support, so good luck with that.

PR checks are always welcome.

[phi-friday]

The code_docs looks like it needs some work. The variable name and type are not separated by a space.

[phi-friday]

The code_docs looks like it needs some work. The variable name and type are not separated by a space.

When written like pbounds: dict, it looks fine, but when written like pbounds : dict, the spaces disappear.

[till-m]

Technically adding a space before the colon is the correct version, as specififed in the numpydoc style guide. Related: ruff feature request for this rule: astral-sh/ruff#8425

[till-m]

I raised an issue about this at jbms/sphinx-immaterial#375

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 96.18%. Comparing base (abdd535) to head (c085670). Report is 5 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #509      +/-   ##
==========================================
+ Coverage   94.70%   96.18%   +1.47%     
==========================================
  Files           9       10       +1     
  Lines         680      864     +184     
==========================================
+ Hits          644      831     +187     
+ Misses         36       33       -3     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[till-m]

Fixed by adding an extension! Link (master only)!

I will backport this fix along with any other changes requested to the v1.5.1 commit once this PR is approved. Until then, I'm marking #510 as a draft.

Before/1.5.1:

After/master:

[till-m]

Added a warning to the .maximize docstring to cover #513.

[till-m]

I backported all configuration changes to the v1.5.1 documentation (e.g. the numpydocs codestyle). From my side, this PR is good to go -- there's nothing I feel the need to change at this stage.

See the demo here.

@fmfn @bwheelz36 I would appreciate if you find a chance to review this. Given that the docs are in a sense the face of this project, I want to make sure no one is unhappy with the outcome.