SAAP docs are built using MkDocs which is based on Python.
This repository has Github action workflow which checks the quality of the documentation and builds the Dockerfile image on Pull Requests. On a push to the main branch, it will create a GitHub release and push the built Dockerfile image to an image repository.
There are at least three options to get fast continuous feedback during local development:
- Build and run the docs using the Dockerfile image
- Run the commands locally
- Use Tilt
Build Dockerfile test image:
$ docker build . -t test
Run test container:
$ docker run -p 8080:8080 test
Then access the docs on localhost:8080
.
Use virtualenvwrapper to set up Python virtual environments.
Install Python 3.
Install mkdocs-material and mermaid plugin:
$ pip3 install mkdocs-material mkdocs-mermaid2-plugin
Finally serve the docs using the built-in web server which is based on Python http server - note that the production build will use Nginx instead:
$ mkdocs serve
or
$ python3 -m mkdocs serve
Markdown linting:
$ brew install markdownlint-cli
$ markdownlint -c .markdownlint.yaml content
Spell checking:
$ brew install vale
$ vale content
Install Tilt, then run:
$ tilt up