Early draft to fix #401

Preview at https://gabdug.github.io/django-components/dev/

To manage the documentation environment, hatch with hatch-mkdocs and hatch-pip-compile has been used.

pipx install hatch
hatch run docs:serve

Features

• Build the documentation using mkdocs and mkdocs-material
  • Lots of extensions and plugins, rich rendering is possible
• Version the documentation with mike
  • Push on a gh-pages branch
• Generate the API reference with mkdocstrings
  • We can add references to our API, Django docs and Python docs
  • We generate an objects.inv file that can be used by others to link to our API

Tasks

• CI to generate on release (tag and latest versions)
• CI to generate the dev version
• CI to generate the documentation on PRs/branches
• API Reference should not have empty pages
  • Either add some documentation (docstring on module, class, function or variable) or remove some pages in scripts/gen_ref_nav.py
• Review and revamp the documentation
• Cleanup the plugins and extensions
• Cleanup the configuration
• Review header levels in the documentation
• Documentation on hatch
• Update CI to remove testing mode (all the XXX)
  • CI should be disabled on forks
• Fix the Github README
  • Should present quickly and redirect to the documentation for more information
  • Links should be to latest/dev doc
• Fix the Pypi README
  • Pypi README can be generated on the fly (with hatch-fancy-pypi-readme for instance)
  • Can have more information than the Github README, but should still redirect to the documentation for more
  • Link should be to the released version (not latest/dev)

Nice to have

• Logo and Favicon?
• Choose a color scheme, or create a custom one?
• Inline examples are included automatically from tests or the example project
• Add mkdocsstrings references where appropriate (in code and in docs)
• Contributors page?
• Proper "added in version x.x" macro?