Migrate to mkdocs

[thomasmarwitz]

Demonstrate how mkdocs-jupyter plugin can be used to execute and render Jupyter Notebooks in a similar way to MyST.

Output: https://metalearners--81.org.readthedocs.build/en/81/

TODO:

• Fix enumeration in background.md
• Docstrings can / should be adapted to mkdocs style
• Jupyter notebooks should be adapted to mkdocs style (remove cell tags)
• Discuss whether jupyter notebooks should be built once and checked into git for fast serving of docs (better DX than slow optuna notebook) => now we have an additional CI action
• Wait for feature: Add option s.t. overridden members are able to "inherit" docstrings from corresponding members in parent classes  mkdocstrings/python#194 => moved to griffe extension: https://github.com/mkdocstrings/griffe-inherited-docstrings (now works with version 1.1.1) TBD: maybe not include in copier template!
• Look into ruff pydocstyle (replacement to pre-commit-hook docformatter) => The docs migration is already huge

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 94.39%. Comparing base (db0828a) to head (4f82bfe).
Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #81      +/-   ##
==========================================
- Coverage   94.74%   94.39%   -0.35%     
==========================================
  Files          15       15              
  Lines        1807     1802       -5     
==========================================
- Hits         1712     1701      -11     
- Misses         95      101       +6     

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

[kklein]

Aside from the math and enumeration topic mentioned above, what do you see as hurdles and next steps?
Might it make sense to test whether our readthedocs setup works fine with mkdocs?

[pavelzw]

BTW an alternative to readthedocs could be github pages in combination with https://github.com/jimporter/mike. Disadvantage would be that there is no preview for PRs. Advantage would be that there is no external configuration necessary.

[kklein]

Sounds interesting! Can we have branch-specific deployments with GitHub-pages? Given our somewhat heavy use of formulas, we rely a lot on rendered docs in PRs.

[thomasmarwitz]

I don't know whether branch based deployments can be accomplished out of the box with mike and gh-pages, that would be interesting to keep an eye on.

I just tried out to host the mkdocs documentation with readthedocs and that worked: https://metalearners--81.org.readthedocs.build/en/81/

[kklein]

@thomasmarwitz sgtm :)

[thomasmarwitz]

@kklein, thanks for your review, I resolved or commented on everything.

Turning the private methods off was also possible :)

[kklein]

Nice to have: if you @kklein still have the original drawio file of the transparent .svg images in docs/imgs/, could you import them with white background? Then switching to darkmode is possible without visual impairments

I added adaptations of the three svg files which should have white background in this commit: 086e3b7

Would you be so kind to give them a shot?

In case there might be further demand for adaptations, you can always import the *.drawio.svg files directly into drawio; the image files themselves contain the source. :)

[pavelzw]

this looks really great, thanks a lot!

i mostly took a look on the framework and left the detailed documentation changes review to @kklein

[pavelzw]

for reference: this is the diff to main (at commit 66074a3)

Dependencies

Explicit dependencies

Dependency1	Before	After	Change	Environments
griffe-inherited-docstrings		1.1.1	Added	docs
mkdocs-jupyter		0.24.8	Added	docs
mkdocs-material		9.6.5	Added	docs
mkdocstrings		0.28.1	Added	docs
mkdocstrings-python		1.16.1	Added	docs
ruff		0.9.7	Added	docs

Implicit dependencies

Dependency1	Before	After	Change	Environments
ghp-import		2.1.0	Added	docs
griffe		1.5.7	Added	docs
jupytext		1.16.7	Added	docs
markdown		3.6	Added	docs
mergedeep		1.3.4	Added	docs
mkdocs		1.6.1	Added	docs
mkdocs-autorefs		1.3.1	Added	docs
mkdocs-get-deps		0.2.0	Added	docs
mkdocs-material-extensions		1.3.1	Added	docs
paginate		0.5.7	Added	docs
pathspec		0.12.1	Added	docs
pymdown-extensions		10.14.3	Added	docs
pyyaml-env-tag		0.1	Added	docs
regex		2024.11.6	Added	docs
watchdog		6.0.0	Added	docs

Footnotes

1. Bold means explicit dependency. ↩ ↩²

[thomasmarwitz]

pixi-diff-to-markdown, right? This is really neat!

[pavelzw]

the light mode version of these images has empty background which looks a bit nicer than this

@kklein could you redo this without background?

[kklein]

I'll take a stab at this after this PR if you don't mind :)

[kklein]

LGTM - thanks a lot!