Mkdocs

[multimeric]

Changes

• Migrate pyslurm to mkdocs + mike (the versioning system)
• A few minor fixes to docstrings to accommodate it: removing backticks and adding newlines in some cases
• Added a docs extra so you can pip install -e .[docs] to install the docs dependencies while developing

Pros & Cons

In my view the benefits of mkdocs are:

• Nicer looking/cleaner docs
• Simpler configuration (only two files needed for the docs in this repo: one markdown, one YAML)

One downside I've identified is that mkdocs (or rather mkdocstrings, 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/134

Preview

Here is an example of how it looks:

[tazend]

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.

[multimeric]

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?

[multimeric]

It looks a bit like this using the readthedocs theme:

[multimeric]

Considering the issue with the function signature not correctly converting, I'm fine to stick with Sphinx if you'd rather.

[tazend]

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)