Documentation¶
Mkdocs(Recommended)¶
Mkdocs
Mkdocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.
Deploy the docs in GitHub Pages¶
Some configuration is needed to deploy the documentation site to GitHub Pages.
Give the GitHub Action permission to deploy the docs
- In the repository:
Setting->Actions->Workflow permissions: SelectRead and write permissions
Why Mkdocs?¶
Markdown is better than reStructuredText¶
Compare to reStructuredText, Markdown is more popular and easier to use.
Material theme is Awesome¶
Material theme is a theme for Mkdocs, it is a modern theme with a focus on usability and customizability.
Material theme: Documentation that simply works
Write your documentation in Markdown and create a professional static site in minutes – searchable, customizable, in 60+ languages, for all devices.
Alternatives¶
Sphinx¶
Some old projects still use Sphinx to generate documentation. But reStructuredText is still not easy to use compare to Markdown.
Sphinx-Immaterial Theme
Sphinx-Immaterial Theme: Adaptation of the popular mkdocs-material material design theme to the sphinx documentation system