Closed multimeric closed 1 year ago
Hi @multimeric
looks good. Do you know if its possible with the material
theme to initially collapse the functions a class has in the table of contents? I feel like that would improve navigation a bit. I've also tried out the readthedocs
theme which does this by default apparently.
It's possible I can just apply the readthedocs
theme if you would prefer. Otherwise I can see if a collapsible panel can be added to the material theme?
It looks a bit like this using the readthedocs
theme:
Considering the issue with the function signature not correctly converting, I'm fine to stick with Sphinx if you'd rather.
Oh I see - didn't get the problem right away with the function signatures, but yeah, thats a bit of a dealbreaker for now. So I would indeed stick to Sphinx if you don't mind and we can improve the current documentation, e.g. adding multiversion and perhaps choosing another Theme that looks a bit more appealing.
Sphinx has a variety of themes to choose from (personally like the read-the-docs theme the most)
Changes
mkdocs
+mike
(the versioning system)docs
extra so you canpip install -e .[docs]
to install the docs dependencies while developingPros & Cons
In my view the benefits of mkdocs are:
One downside I've identified is that
mkdocs
(or rathermkdocstrings
, the Python documentation plugin) doesn't understand that Cython generates the Python function signatures, so the first line of each function is the "true" signature. See: https://github.com/mkdocstrings/griffe/issues/134Preview
Here is an example of how it looks:![image](https://user-images.githubusercontent.com/5019367/221786279-6b08e92a-58ef-4ad1-9010-4f82c8a6a8ef.png)