search

appliedAI-Initiative / pymetrius

A fire-tested template for production grade python libraries and packages.
MIT License
14 stars 2 forks source link

Move to mkdocs #8

Open mdbenito opened 1 year ago

mdbenito commented 1 year ago

Sphinx is a constant source of indescribable pain and frustration. Countless hours wasted staring at bogus error messages because of a missed white space somewhere or something even more idiotic. Almost infinite build times consuming the forests of the Earth.

If mkdocs supports bibtex and latex-style dollar inline math, let's switch and never look back

MischaPanch commented 8 months ago

Moved to jupyter-book (which is kinda still sphinx). Should work nicely for now

mdbenito commented 8 months ago

Moved to jupyter-book (which is kinda still sphinx). Should work nicely for now

The issue with sphinx is not how it renders, but its appalling error reporting, which paired with a terribly finicky parser make for infinite debug loops and enormous time wasted. I don't think Jupyter book addresses any of these problems.

MischaPanch commented 8 months ago

Let's see for how long the current setup will work without me having to touch it in tianshou and other projects created by this template.

I am agnostic about which tool to use, but I won't have time in the foreseeable future to make the move to mkdocs.

For anyone interested in this issue: an mkdocs based setup should reproduce the nice rendering, caching and execution of notebooks that jupyter book currently provides

mdbenito commented 7 months ago

For reference / inspiration: pyDVL uses mkdocs, mkdocs-material as template and mike for versioning.