scanapi/scanapi

Add contributor documentation for MkDocs and Read the Docs workflow

Open

#930 opened on 2026年5月19日

GitHub で見る
 (3 comments) (0 reactions) (1 assignee)Python (1,311 stars) (78 forks)batch import
DocumentationGood First IssueWiki

説明

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.yml is organized
  • How .readthedocs.yaml works
  • 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-install Installs documentation development dependencies using uv sync --extra dev.

  • make docs-serve Starts a local MkDocs server with hot reload enabled, allowing contributors to preview documentation changes while editing.

  • make docs-build Builds the documentation site locally into the site/ directory, simulating the generated output used by MkDocs.

  • make docs-clean Removes generated documentation artifacts by deleting the site/ 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.

コントリビューターガイド