Convert documentation from Sphinx to MkDocs

[tleonhardt]

One idea I've been toying around with in my head is porting cmd2's documentation from using Sphinx to using MkDocs.

ReadTheDocs supports MkDocs and MkDocs has been rapidly growing in popularity. In summary it is similar to Sphinx but uses Markdown instead of reStructuredText.

I figure that in this day and age, essentially all developers know Markdown, but knowledge of reStructuredText is much less common. So it would likely help others help us maintain the documentation.

As long as nobody objects, I'll likely start experimenting with this soon. But I'd like to hear what other contributors think ...

[tleonhardt]

I did some research and looked at seven popular Python projects which use MkDocs and they all use the Material Theme for MkDocs.

For reference, here are the projects I looked at:

• AutoGPT
• hello-algo
• FastAPI
• ruff
• uv
• polars
• pydantic

I also found this tool for automatically translating from existing Sphinx docs to MkDocs with a material theme: MkDocs Translate

One other possibility is that now Sphinx supports Markdown via the MyST Parser in addition to reStructuredText. So we could still use Sphinx, but use Markdown files with it.

[tleonhardt]

The MkDocs Catalog has ranked lists of MkDocs themes, markdown extensions, and plugins.

ReadTheDocs has this handy guide on how to use Material for MkDocs with ReadTheDocs.

[kotfu]

Markdown is great, and I'm all in favor of switching our documentation to it. I have no preference whether we stick with Sphinx or switch to MkDocs. No preference on theme either, Material is commonly used and I think works just fine.

[kotfu]

Should we decide to make this change, I'm happy to help convert/migrate files from RST to Markdown.

[tleonhardt]

ReadTheDocs has this demo repository that shows a correct bare-bones configuration for using Material for MkDocs with ReadTheDocs.

[tleonhardt]

@kotfu I have a WIP PR up: #1397

It is about 75% done but if you have some time I could use some help fixing the numerous minor translation bugs. I went through the site linearly and fixed stuff page by page. I stopped at features/disable_commands.md

Build is working and TODO list is in the PR.

[tleonhardt]

@kotfu @kmvanbrunt I'm now very close to done with the WIP PR: #1397

It is now fully functional - docs have been converted to Markdown, MkDocs Material theme build is working, looks good, and is integrated with our GitHub Action CI and all Sphinx stuff has been removed.

The only thing remaining is for me to do some manual testing to verify the ReadTheDocs build is working fine.

TL;DR on using the new stuff:

Start a live HTML server that auto-reloads on changed Markdown files:

mkdocs serve

or equivalently:

inv livehtml

Build the docs:

mkdocs build

or equivalently:

inv docs

P.S. If you have uv installed, then do setup a fully functional virtual environment with everything you need for cmd2 dev, just do this from the project root:

uv venv

[tleonhardt]

PR is now done and no longer a WIP