Michael Adam
93179a41f3
This reworks the docs-check ci workflow in several ways: * It renames the make target 'check-docs' to the more systematic 'check.docs'. * It adds a 'docs'mode to the files validation script, and uses the script in `make check.docs`. Overall, the workflow and local make targets are more systematic and consistent with this change. Signed-off-by: Michael Adam <obnox@samba.org>
2.1 KiB
title
| title |
|---|
| Documentation |
We are using MkDocs with the Material for MkDocs theme.
Markdown Extensions
Thanks to the MkDocs Material theme we have certain "markdown syntax extensions" available:
For a whole list of features Reference - Material for MkDocs.
Local Preview
To locally preview the documentation, you can run the following command (in the root of the repository):
make docs-preview
When previewing, now you can navigate your browser to http://127.0.0.1:8000/ to open the preview of the documentation.
!!! hint
Should you encounter a command not found error while trying to preview the docs for the first
time on a machine, you probably need to install the dependencies for MkDocs and extensions used:
pip3 install -r build/release/requirements_docs.txt. Make sure that your Python binary path is
included in your PATH.
Making docs
helm-docs is a tool that generates the documentation for a helm chart automatically. If there are changes in the helm chart, the developer needs to run make docs (to run helm-docs) and check in the resulting autogenerated files.
To make it easy to check locally for uncommitted changes generated by make docs, an additional make target exists: simply running make check.docs will run the docs auto-generation and will complain if this produces uncommitted changes to doc files. It is therefore a good habit to always run make check.docs locally before creating or updating a PR.