Writing Documentation

The OEPS Documentation (which you are reading right now) is built with mkdocs and hosted on Github pages. All content is stored in Markdown .md files inside of the docs/src directory. If you are making small changes, you can can update the Markdown files directly, commit your changes, and then simply wait for the Github pages deployment to be rebuilt.

Tip

The docs are built and uploaded to Github pages within a single workflow.

In the event that you are doing anything more substantial than basic changes to a single page, then you will want to build the docs locally to preview them before committing and publishing your changes.

Local docs build

Enter the docs directory, create a Python virtual environment, and activate it:

cd docs
python3 -m venv env
source ./env/bin/activate

Then, run the following command to preview a build of the docs:

mkdocs serve

Visit http://localhost:8000 to view the docs, and any changes to Markdown files in /docs/src will be automatically reflected in the preview.

Warning

All files inside of docs/src/reference are autogenerated by CLI commands, so those files should never be edited directly.