Read the Docs setup

The PMSM documentation is built with MkDocs and the Material theme. Read the Docs runs that build on every push to your default branch.

One-time project import

1. Sign in at readthedocs.org (GitHub login is supported).
2. Click Import a Project and connect the PrestonHager/PMSM GitHub repository (or your fork).
3. Read the Docs detects readthedocs.yaml at the repo root and uses it for the build configuration (Python 3.12, MkDocs).
4. Choose a slug (e.g. pmsm). The docs will be served at https://<slug>.readthedocs.io/ unless you attach a custom domain.

Build behavior

• Builds run automatically when you push to the tracked branch (usually main).
• Pull request builds can be enabled in the RTD project Admin so contributors get preview links.

Local preview

Same commands as in Development:

pip install -r requirements-docs.txt
mkdocs serve

To match Read the Docs exactly:

mkdocs build --strict

Configuration files in the repo

File	Role
mkdocs.yml	Site name, theme, navigation, plugins
readthedocs.yaml	RTD v2 config (OS, Python, MkDocs, fail_on_warning)
requirements-docs.txt	Pinned Python dependencies for the build

If the RTD build fails, open the Builds tab for the project and expand the log; warnings are treated as errors when fail_on_warning: true is set.