One best practice we follow regarding documentation is to keep it close to what it describes, we prefer including those files together with the actual code, in a different
docs/ folder. We write them in Markdown because it is a simple and easy to understand format that is automatically rendered correctly when browsing those files in Gitlab.
Using mkdocs for generating public documentation
There is Gitlab repository that demonstrates this process, important bits about this specific repository are:
.gitlab-ci.ymlconfiguration explicitly using the forked image and copying the CSS fixes before the build, and
- mkdocs-mermaid forked plugin that includes specific fixes for the bundle
readthedocstheme and docker support.
The final result: