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), additionally, discuss whether jupyter notebooks should be built once and checked into git for fast serving of docs (better DX than slow optuna notebook).
• 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 template!
• Look into ruff pydocstyle (replacement to pre-commit-hook docformatter)

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 94.73%. Comparing base (a4858da) to head (cb6c281).

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #81   +/-   ##
=======================================
  Coverage   94.73%   94.73%           
=======================================
  Files          15       15           
  Lines        1806     1806           
=======================================
  Hits         1711     1711           
  Misses         95       95           

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

[thomasmarwitz]

One issue I discovered with math blocks (= math formulae that are not rendered inline).

For some reason KaTeX is only able to render math blocks if there is no indentation before them which is annoying when dealing with enumerated lists:

Math works, enumeration doesn't (1. and 1.):

Enumeration works, math doesn't:

I haven't looked into MathJax yet. Other solutions could be to use unordered lists or use headings instead:

[kklein]

Thanks for looking into this @thomasmarwitz !
Is it possible that the subscripts no longer need escaping?

See

from this PR compared to

from https://metalearners.readthedocs.io/en/latest/background.html#x-learner

[thomasmarwitz]

@kklein Thanks for pointing that out, looks like I completely missed this. You are right, you don't need to escape subscript anymore.

[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/

[thomasmarwitz]

During porting the rest of the documentation I noticed:

Mkdocs does (by default) not display methods if docstring is missing. For classes that override a method but don't add a docstring, this method is not listed in the API doc:

Example of method from RLearner:

Mkdocs does only include 2 methods (with "own" docstring):

Sphinx on the other hand includes these methods because they "inherit" the docstring:

[thomasmarwitz]

@kklein pointed out this mkdocstrings feature ¹.

It adds inherited methods (w/ a docstring) to subclasses. However, it still differs slightly from the sphinx behavior:

In the case above, SLearner overwrites evaluate w/o providing a docstring in the overwritten impl. Therefore, this method doesn't appear in contrast to sphinx's way of handling this.

But perhaps this is even desired behavior? In the sense that if you change the implementation, you should also adapt the docstring?

Footnotes

1. https://mkdocstrings.github.io/python/usage/configuration/members/#inherited_members ↩

[kklein]

But perhaps this is even desired behavior? In the sense that if you change the implementation, you should also adapt the docstring?

I can totally see that one might want to ask that question. In our case we mostly described the 'contract' of a given method/function in the docstrings, i.e. what a user may provide as input and what they can expect as an output. We don't usually say much about the 'how's.

At times, changing the implementation does not change this contract.

E.g. one might think of the folllowing:

class Shape:
    contour: list[Point]
    def surface_area(self):
        """Return the surface area in square meters."""
        return numerical_integration(self.contour)
        
class Rectange(Shape)
    def surface_area(self):
        return distance(self.cotour[2], self.contour[0]) * distance(self.contour[3], self.contour[1])

In this case we used said sphinx feature in order to DRY and reduce the risk of inconsistencies due to redundancy.

[pavelzw]

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.

I don't think so, so in this case readthedocs might be more fitting.
Note though, that with mkdocs you can easily spin up a dev docs instance using pixi run docs or pixi run mkdocs serve.

[thomasmarwitz]

check "true" possible?

[pavelzw]

Suggested change

	Hides the In[ ] blocks.
	Out[ ] blocks are not displayed.
	Hides the In[ ] blocks in rendered jupyter notebooks.
	Out[ ] blocks are not displayed.

[pavelzw]

is this still needed?

[pavelzw]

how about pixi run docs for interactive docs serving and pixi run docs-build for building the HTML?

i'm also wondering whether we should add --strict to docs-build, xref https://github.com/prefix-dev/pixi/blob/e56f2e6300ba2defbd322fc13a45f224886a89c4/pixi.toml#L122