Maintainer Guide¶

Project layout¶

Project structure

├── docker-compose.yml # Config to tag and run the image container
├── Dockerfile         # Instructions to build the image
├── docs/              # Contains documentation pages
├── mkdocs.yml         # MkDocs configs
├── pyproject.toml     # Poetry configs
├── requirements.txt   # Python packages list (generated)
└── scripts
    └── export_requirements.sh # Generates the requirements file

We are following this guide for multiplatform builds. It recommends a matrix strategy if we ever need to add more platforms.

How to run MkDocs¶

These are the ways to run MkDocs within this project.

DockerLocal install (pip)Local install (poetry)

Docker¶

This option is required for the other maintenance steps below.

Build the image
```
docker-compose build
```
Start the container
```
docker-compose up
```
Open a browser to http://localhost:8000/ to view the documentation locally
Modify the files in the docs/ directory. The site will auto update when the files are saved.
Quit

Ctrl+C to quit the local server and stop the container

Local Install (pip)¶

python should be version 3

Install mkdocs
```
pip install -r requirements.txt
```
Start the local server
```
mkdocs serve -a localhost:8000
```
Open a browser to http://localhost:8000/ to view the documentation locally
Modify the files in the docs/ directory. The site will auto update when the files are saved.
Quit

Ctrl+C to quit mkdocs

Local Install (poetry)¶

python poetry must be installed in the local system. We recommend installing via pipx into an isolated environment.

Install mkdocs
```
poetry install
```

Start the local server

poetry run mkdocs serve -a localhost:8000

Open a browser to http://localhost:8000/ to view the documentation locally
Modify the files in the docs/ directory. The site will auto update when the files are saved.
Quit

Ctrl+C to quit mkdocs

How to update the package versions¶

Staying updated may give us speed improvements (python), better security, and bugfixes. Docker hub, for example, can scan image layers to find packages with security advisories. These are the steps to update the package versions.

Add poetry to the container

Update packages using poetry

docker-compose exec mkdocs sh -c "poetry update"

Export requirements.txt
scriptcommand
./scripts/export_requirements.sh
# (1)! docker-compose exec mkdocs \ poetry export -f requirements.txt > requirements.txt # (2)!
1. This docker-compose command runs the second line inside the docker container
2. Export in requirements.txt format, to requirements.txt.

Commit the requirements file

git add requirements.txt poetry.lock
git commit -m"chore: update package versions"

Once merged into main, the CI will build the new image and upload it with the latest tag.

How to add an MkDocs plugin¶

Let's say we want to add the mkdocs-multirepo-plugin.

Add poetry to the container

Install the new MkDocs plugin

docker-compose exec mkdocs sh -c "poetry add mkdocs-multirepo-plugin"

Export requirements.txt
scriptcommand
./scripts/export_requirements.sh
# (1)! docker-compose exec mkdocs \ poetry export -f requirements.txt > requirements.txt # (2)!
1. This docker-compose command runs the second line inside the docker container
2. Export in requirements.txt format, to requirements.txt.
Add any system dependencies in the Dockerfile

We're adding git here, which is a dependency of mkdocs-multirepo-plugin
Dockerfile
```
...
# install system dependencies
RUN \
  --mount=type=cache,target=/var/cache \
  apk add \
  git=2.40.1-r0
# (1)!
...
```
1. Mount the /var/cache directory as cache in docker when running the command

Commit requirements.txt and Dockerfile

git add requirements.txt Dockerfile pyproject.toml poetry.lock
git commit -m"feat: add plugin mkdocs-multirepo-plugin"

Once merged into main, the CI will build the new image and upload it with the latest tag.

How we set it up

Setup from scratch¶

Here's the recommended setup, from our experience setting it up.

Project directory¶

mkdir mkdocs-notes && cd $_

Poetry project¶

poetry init —name docs —description “Project Documentation” # (1)!
# use a modern stable python like version 3.11.4
# don’t define dependencies interactively

We chose poetry because it performs multiple useful functions such as creating the virtual environment and dependency management. It will be easy to update to the latest versions of dependencies.

Mkdocs package¶

poetry run poetry add mkdocs

Mkdocs project¶

mkdocs new . # creates mkdocs project in current directory

Local dev server¶

mkdocs serve —dev-addr 0.0.0.0:8000 # (1)!

Start the dev server locally on any address on port 8000. This is useful for development from a different local network computer, where the default localhost won’t work

Material theme¶

poetry add mkdocs-material
cat "theme: material" >> mkdocs.yml
git ci -a -m"setup material theme for mkdocs"

Multirepo (not yet working)¶

poetry add mkdocs-multirepo-plugin
# add the plugin in mkdocs.yml
# import the other repos in mkdocs.yml

Export requirements¶

We need to export the requirements whenever we add a new package, so that the docker setup and pip users can know to use it.

# (1)!
poetry export -f requirements.txt > requirements.txt

This is also contained in a script export_requirements.sh in the scripts directory

Deployment to Github Pages¶

We closely followed this guide. This setup creates a gh-pages branch to store the latest docs. Make the necessary configurations in the Github repo settings as necessary under Pages.

Docker setup¶

We modified the dockerfile and docker-compose files from People Depot to install and serve mkdocs locally. The files are docker-compose.yml and Dockerfile.