Add contributor documentation for MkDocs and Read the Docs workflow
#930 opened on 2026年5月19日
説明
Feature request
Description the feature
Add documentation explaining the project's MkDocs and Read the Docs workflow.
This documentation should live inside /wiki and be included in the Wiki table of contents (/wiki/README.md) so contributors can easily find it.
The page should explain how documentation is structured and maintained, including:
- Documentation structure and file locations
- How
mkdocs.ymlis organized - How
.readthedocs.yamlworks - Documentation deployment flow
- Common troubleshooting steps
It should also explain that https://scanapi.readthedocs.io/en/latest/ is built automatically by Read the Docs, which listens to GitHub webhooks and triggers new builds after documentation related changes are pushed.
The page should also document the existing Makefile commands used for docs development:
-
make docs-installInstalls documentation development dependencies usinguv sync --extra dev. -
make docs-serveStarts a local MkDocs server with hot reload enabled, allowing contributors to preview documentation changes while editing. -
make docs-buildBuilds the documentation site locally into thesite/directory, simulating the generated output used by MkDocs. -
make docs-cleanRemoves generated documentation artifacts by deleting thesite/directory.
Is your feature request related to a problem?
The project recently migrated documentation tooling, and contributors may not be familiar with how MkDocs and Read the Docs are configured.
Without dedicated documentation, contributors may need to rediscover implementation details or spend additional time understanding how documentation builds, deployment, and local workflows work.
Do you have any suggestions on how to add this feature in scanapi ?
Create a dedicated page under /wiki, add it to /wiki/README.md, and document the end to end documentation workflow from local development to automatic deployment through Read the Docs.