Open
Description
Currently, in the template the documentation is generated using Sphinx. However, MkDocs offers a more modern and streamlined approach to documentation generation that could simplify our workflow and provide a better experience for developers and users.
Some of the advantages:
- MkDocs uses a single
mkdocs.yml
file for configuration, which is easier to manage and less complex compared to Sphinx’s configuration files (conf.py
and others). - MkDocs uses Markdown natively for writing documentation, which is more user-friendly and widely used compared to Sphinx's reStructuredText (
.rst
). - MkDocs offers a variety of modern themes like "Material for MkDocs", which provide a clean and responsive design out of the box. The plugin ecosystem for MkDocs is robust and growing, with many plugins that can enhance the documentation experience.
- MkDocs tends to be faster in generating static sites, which could lead to quicker build times, especially for larger projects.
- MkDocs provides built-in support for enhanced navigation, including sidebars and table of contents, and a powerful full-text search, making it easier for users to find information quickly.