Blaine Gardner
c9d99e01a0
mkdocs uses a markdown renderer that is hardcoded to 4 spaces per tab
for detecting indentation levels, including ordered- and
unordered-lists. Since we cannot easily change the renderer, begin using
a markdown linter in CI that will fail if official docs do not adhere to
the spacing rules.
As a starting point, the markdownlint config does not begin with the
default set of checks, which might overwhelm attempts to fix them.
Instead, focus on list-tab-spacing rules and a few other highly useful
checks.
markdownlint also has some gaps in its abilities that allow common Rook
doc issues to pass acceptance. However, it allows creating custom
linting plugins. Create 2 such linting plugins to check 2 things:
- all doc lines (except code blocks) must be aligned to a 4-space
boundary, without exception. This ensures that markdown will render
correctly with mkdocs. This unfortunately makes it possible to create
lists that are internally aligned strangely.
- admonitions must all follow the same format of
```
!!! header
body
```
For the strange lists, this is allowed and renders correctly, but it
looks strange:
```md
- first bullet
- second bullet
still second bullet
- third bullet
has a paragraph
of text inside
- last bullet
Signed-off-by: Blaine Gardner <blaine.gardner@ibm.com>
39 lines
2.1 KiB
Markdown
39 lines
2.1 KiB
Markdown
---
|
|
title: Documentation
|
|
---
|
|
|
|
We are using [MkDocs](https://www.mkdocs.org/) with the [Material for MkDocs theme](https://squidfunk.github.io/mkdocs-material/).
|
|
|
|
## Markdown Extensions
|
|
|
|
Thanks to the MkDocs Material theme we have certain "markdown syntax extensions" available:
|
|
|
|
* [Admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/)
|
|
* [Footnotes](https://squidfunk.github.io/mkdocs-material/reference/footnotes/)
|
|
* [Icons, Emojis](https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/)
|
|
* [Task lists](https://squidfunk.github.io/mkdocs-material/reference/lists/#using-definition-lists)
|
|
* And [more](https://squidfunk.github.io/mkdocs-material/reference/)..
|
|
|
|
For a whole list of features [Reference - Material for MkDocs](https://squidfunk.github.io/mkdocs-material/reference/).
|
|
|
|
## Local Preview
|
|
|
|
To locally preview the documentation, you can run the following command (in the root of the repository):
|
|
|
|
```console
|
|
make docs-preview
|
|
```
|
|
|
|
When previewing, now you can navigate your browser to [http://127.0.0.1:8000/](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](https://github.com/norwoodj/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.
|