Description:

The current documentation for Eurybia is built using Sphinx and hosted on ReadTheDocs. While this setup works fine, we propose migrating the documentation to MkDocs for the following reasons:

Why MkDocs?

• Markdown-based: MkDocs uses Markdown for documentation, which is easier for most developers and contributors to work with, compared to reStructuredText used by Sphinx.
• GitHub Integration: MkDocs can be directly integrated with GitHub Pages, enabling seamless deployment and hosting from within the GitHub environment.
• Simplified Configuration: Compared to Sphinx, MkDocs offers a simpler configuration and build process, making it more straightforward to maintain.
• Modern Themes: MkDocs offers elegant and responsive themes (e.g., mkdocs-material), which provide a clean, user-friendly interface out of the box.

Suggested Steps

1. Set up the initial MkDocs project with mkdocs.yml and the docs/ directory.
2. Migrate the documentation content from .rst to .md format.
3. Choose and configure an MkDocs theme, such as mkdocs-material, for an improved user interface.
4. Set up continuous deployment to GitHub Pages using GitHub Actions or another CI tool.
5. Update the contribution guidelines to reflect the new documentation process and format.

Optional

• Implement versioning using tools like mike or similar.
• Integrate a search feature, either natively or via MkDocs plugins.