Set up MkDocs (Material) + Read the Docs with versioned public docs and strict CI docs checks

[Copilot]

• Review new PR feedback and inspect current README/docs layout
• Run baseline project checks before new edits
• Restructure README documentation-related sections so docs/man pages are grouped coherently
• Ensure README ordering ends with: Support this project, Contributing, License
• Re-run targeted validation for changed docs content
• Run final automated review (code_review) and security scan (codeql_checker)
• Reply to PR comment with commit hash and screenshot

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Feature] Set up public documentation site with Read the Docs, MkDocs, and versioned docs</issue_title>
<issue_description>### Problem

The project currently has limited markdown docs in-repo, but no hosted public documentation site, no standardized docs build workflow, and no release-versioned docs experience.

Design

Adopt MkDocs for docs generation and Read the Docs for hosting/versioning.

Use docs/ as public documentation source.
Keep non-public material under docs/internal/ and exclude it from published nav/output.

Versioning model:

1. latest from main
2. stable from latest release
3. Semver tags (vX.Y.Z) as explicit versions

Scope

• Add MkDocs config (mkdocs.yml) and docs dependency manifest.
• Add Read the Docs config (.readthedocs.yml).
• Establish public docs navigation from docs/ pages.
• Exclude docs/internal/ from public navigation/output.
• Add CI docs build check (mkdocs build --strict).
• Add docs link/badge and docs authoring instructions in README.md.
• Configure Read the Docs project for latest, stable, and semver tag versions.

Boundary

• No migration to GitBook or README.com in this phase.
• No publication of internal docs under docs/internal/.
• No custom docs backend/service beyond Read the Docs + MkDocs.

Acceptance Criteria

• Docs build passes locally and in CI using mkdocs build --strict.
• Read the Docs successfully builds latest, stable, and semver-tagged versions.
• Public docs are linked from README.md.
• Version selector exposes expected versions.
• docs/internal/ content is not exposed in public docs nav/site.

Context

This setup gives low-friction OSS documentation hosting with strong versioning support and GitHub-native workflow integration.

• Read the Docs + MkDocs: https://docs.readthedocs.com/platform/stable/intro/mkdocs.html
• MkDocs configuration: https://www.mkdocs.org/user-guide/configuration/
• Read the Docs versioning: https://docs.readthedocs.com/platform/stable/versions.html
  </issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [Feature] Set up public documentation site with Read the Docs, MkDocs, and versioned docs #49

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	pypi/​mkdocs@​1.6.1
	pypi/​mkdocs-material@​9.6.12

View full report

[mbe24]

@copilot the .readthedocs.yaml in the example looks like this:

 version: 2

 build:
   os: "ubuntu-24.04"
   tools:
     python: "3"
   # We recommend using a requirements file for reproducible builds.
   # This is just a quick example to get started.
   # https://docs.readthedocs.io/page/guides/reproducible-builds.html
   jobs:
     pre_install:
       - pip install mkdocs-material

 mkdocs:
   configuration: mkdocs.yml

it is using the material theme. Could you do that, too? mkdocs.yml contains this:

 theme:
   name: material

For more information regarding the material theme, please look here: https://github.com/squidfunk/mkdocs-material

Also, please add little more documentation and context.

[mbe24]

@copilot Thanks, looks good. But the README.md now has document authoring section next to the thematically-related Man Pages section. Maybe we could subsume them under one section? Maybe documentation? With two subsections? Please think about sth. that makes sense. Also, please think about the location. The last 3 sections should definitely be Support this project, Contributing, and License.

[Copilot]

@copilot Thanks, looks good. But the README.md now has document authoring section next to the thematically-related Man Pages section. Maybe we could subsume them under one section? Maybe...

Updated in commit 368fa3b: I grouped the README doc content under a single Documentation section with Man Pages and Documentation Authoring subsections, and reordered sections so the final three are now Support this project, Contributing, and License.

Screenshot: https://github.com/user-attachments/assets/3b29adbd-7bb7-46ed-b184-97c587495ef1