Switch docs to mkdocs directly

[JacobHayes]

Is your feature request related to a problem? Please describe.

We use portray for docs right now to combine mkdocs (written) and pdocs (code generated) documentation. However, portray and pdocs don't seem to be actively maintained (same author) and have a few issues:

• portray seems to have a few config edge cases (eg: can't get syntax highlighting, the API reference doc links are dead, etc)
• pdocs was originally forked from pdoc for not being maintained (reverse is true now) and missing .md output (since added)
• pdocs doesn't include class comments (likely something we could fix, but work 🤷) and shows all inherited methods inline (which is annoying for pydantic model subclasses... ie: everything)
• pdocs breaks on generics (eg: list[int]) requiring a fork (since PR likely won't be merged)

Describe the solution you'd like

The code docstrings aren't the most important to document (nor in the best shape), so might be fine to scrap portray+pdocs and only use mkdocs for hand crafted documentation.

When we get around to code docs, pdoc worked a bit better (hiding inherited methods, showed class docstrings, etc) but doesn't include submodules when using __all__ (unless you explicitly add them to __all__, which won't work for the ones we intend to be dynamically imported). It's possible we could change the template or similar, but can punt.

Describe alternatives you've considered A clear and concise description of any alternative solutions or features you've considered:

Additional context Add any other context or screenshots about the feature request here:

[mhils]

If you are using mkdocs anyways, you should add https://github.com/mkdocstrings/mkdocstrings to the list. :)

(unless you explicitly add them to all, which won't work for the ones we intend to be dynamically imported)

I don't know what exactly your setup is, but if you dynamically modify __all__ that would be picked up by pdoc as well. Template changes do not work right now as mod.submodules already considers __all__, but if you have a strong interest in that I'd be happy to take a closer look and see if we could change that. :)

[JacobHayes]

If you are using mkdocs anyways, you should add https://github.com/mkdocstrings/mkdocstrings to the list. :)

@mhils that sounds perfect - I'll add that when I start changing things over, thanks for the tip!