From bd7050897dc1569908fcf94bb04fae5ecb857eac Mon Sep 17 00:00:00 2001 From: "Leandro G. Almeida" Date: Sat, 30 May 2026 12:14:14 -0700 Subject: [PATCH] =?UTF-8?q?=F0=9F=9A=9A=20docs:=20switch=20generated=20doc?= =?UTF-8?q?s=20tooling=20to=20ProperDocs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Makefile | 8 ++++---- docs/concepts/generated-project.md | 2 +- docs/development/README.md | 2 +- docs/development/additional-resources.md | 2 +- docs/development/documentation.md | 6 +++--- docs/development/tools.md | 10 +++++----- pyproject.toml | 3 +-- src/repoman/main_template/README.md.jinja | 2 +- .../main_template/config/vscode/launch.json.jinja | 2 +- src/repoman/main_template/make_cmds/documentation.mk | 6 +++--- src/repoman/main_template/pyproject.toml.jinja | 2 +- .../workflows/docs.yml.jinja | 2 +- tests/test_template/test_ci.py | 12 +++++++++--- 13 files changed, 32 insertions(+), 27 deletions(-) diff --git a/Makefile b/Makefile index ce5a47f..51f187a 100644 --- a/Makefile +++ b/Makefile @@ -132,17 +132,17 @@ docs-trees: ## Regenerate tree blocks in documentation uv run python scripts/gen_tree_docs.py docs: ensure-docs-coverage-report ## Build documentation - uv run mkdocs build --config-file=config/mkdocs.yml + uv run properdocs build --config-file=config/mkdocs.yml docs-serve: ensure-docs-coverage-report ## Serve documentation locally - uv run mkdocs serve --config-file=config/mkdocs.yml + uv run properdocs serve --config-file=config/mkdocs.yml docs-serve-open: ensure-docs-coverage-report ## Serve documentation and open in default browser @(sleep 2 && uv run python -m webbrowser "http://127.0.0.1:8000") & - uv run mkdocs serve --config-file=config/mkdocs.yml + uv run properdocs serve --config-file=config/mkdocs.yml docs-check: ensure-docs-coverage-report ## Check documentation for issues - uv run mkdocs build --config-file=config/mkdocs.yml --strict + uv run properdocs build --config-file=config/mkdocs.yml --strict check-docs: docs-check ## Alias for docs-check diff --git a/docs/concepts/generated-project.md b/docs/concepts/generated-project.md index a96a6ff..2235eac 100644 --- a/docs/concepts/generated-project.md +++ b/docs/concepts/generated-project.md @@ -8,7 +8,7 @@ Generated projects typically include: - `src//` for the main Python package - `tests/` for pytest-based tests -- `config/` for Ruff, MyPy, pytest, MkDocs, and related config +- `config/` for Ruff, MyPy, pytest, ProperDocs, and related config - `docs/` for project documentation - `make_cmds/` for Makefile fragments - `pyproject.toml` for package metadata and dependencies diff --git a/docs/development/README.md b/docs/development/README.md index fba9824..393509d 100644 --- a/docs/development/README.md +++ b/docs/development/README.md @@ -57,7 +57,7 @@ Welcome to the repoman development environment! This guide will help you set up - **[Code Quality](code-quality.md)** — Linting (Ruff), type checking (MyPy) - **[CLI messages](cli-messages.md)** — Centralized error/warning message text and panels - **[Config validation](config-validation.md)** — Pydantic-based answers validation flow -- **[Documentation](documentation.md)** — MkDocs, Material theme, building docs +- **[Documentation](documentation.md)** — ProperDocs, Material for MkDocs theme, building docs - **[CI](ci.md)** — Continuous integration and local simulation - **[Debugging](debugging.md)** — Common issues and debug tools - **[Performance Tips](performance-tips.md)** — Fast development workflow diff --git a/docs/development/additional-resources.md b/docs/development/additional-resources.md index 0b2e20a..0b5c4ff 100644 --- a/docs/development/additional-resources.md +++ b/docs/development/additional-resources.md @@ -10,7 +10,7 @@ - **[uv Documentation](https://docs.astral.sh/uv/)**: uv package manager guide - **[Pytest Documentation](https://docs.pytest.org/)**: Testing framework guide - **[Ruff Documentation](https://docs.astral.sh/ruff/)**: Linting and formatting guide -- **[MkDocs Documentation](https://www.mkdocs.org/)**: Static site generator guide +- **[ProperDocs Documentation](https://properdocs.org/)**: Static site generator guide - **[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)**: Theme documentation - **[mkdocstrings Documentation](https://mkdocstrings.github.io/)**: API documentation generator diff --git a/docs/development/documentation.md b/docs/development/documentation.md index 9574b87..992a1a8 100644 --- a/docs/development/documentation.md +++ b/docs/development/documentation.md @@ -1,6 +1,6 @@ # Documentation -The project uses **MkDocs** with the **Material theme** for documentation. This provides a modern, responsive documentation site with excellent features like search, navigation, and code highlighting. +The project uses **ProperDocs** with the **Material for MkDocs theme** for documentation. This provides a modern, responsive documentation site with excellent features like search, navigation, and code highlighting. ## Documentation Structure @@ -59,7 +59,7 @@ docs ``` -MkDocs is configured in `config/mkdocs.yml` (in the repo root). The `docs_dir` points to this `docs/` folder. +ProperDocs is configured in `config/mkdocs.yml` (in the repo root). The `docs_dir` points to this `docs/` folder. ## Documentation map @@ -104,7 +104,7 @@ flowchart LR update --> troubleshooting ``` -## MkDocs Configuration +## ProperDocs Configuration The documentation is configured in `config/mkdocs.yml` with the following features: diff --git a/docs/development/tools.md b/docs/development/tools.md index bfb7c18..f67b6ad 100644 --- a/docs/development/tools.md +++ b/docs/development/tools.md @@ -112,10 +112,10 @@ format: uv run ruff format src/ tests/ docs: - uv run mkdocs build --config-file=config/mkdocs.yml + uv run properdocs build --config-file=config/mkdocs.yml docs-serve: - uv run mkdocs serve --config-file=config/mkdocs.yml + uv run properdocs serve --config-file=config/mkdocs.yml clean: rm -rf build/ dist/ *.egg-info/ .pytest_cache/ htmlcov/ site/ @@ -130,11 +130,11 @@ To add documentation commands to your Makefile, add these lines: # Documentation # ####################### docs: ## Build documentation - uv run mkdocs build --config-file=config/mkdocs.yml + uv run properdocs build --config-file=config/mkdocs.yml docs-serve: ## Serve documentation locally - uv run mkdocs serve --config-file=config/mkdocs.yml + uv run properdocs serve --config-file=config/mkdocs.yml docs-check: ## Check documentation for issues - uv run mkdocs build --config-file=config/mkdocs.yml --strict + uv run properdocs build --config-file=config/mkdocs.yml --strict ``` diff --git a/pyproject.toml b/pyproject.toml index 08da71c..6e16ca5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -64,12 +64,11 @@ docs = [ "mkdocs-literate-nav>=0.6.1", "mkdocs-minify-plugin>=0.8.0", "mkdocs-jupyter>=0.24.8", - "mkdocs>=1.6.1", "mkdocstrings[python]>=1.0.0", "mkdocs-table-reader-plugin>=3.1.0", "mkdocs-charts-plugin>=0.0.13", "pymdown-extensions>=10.12", "mkdocs-material>=9.7.6", + "properdocs>=1.6.7", ] - diff --git a/src/repoman/main_template/README.md.jinja b/src/repoman/main_template/README.md.jinja index 16ea2de..9354d01 100644 --- a/src/repoman/main_template/README.md.jinja +++ b/src/repoman/main_template/README.md.jinja @@ -13,7 +13,7 @@ {% if repository_provider == "github" and (not insiders or public_release) -%} [![ci](https://github.com/{{ repository_namespace }}/{{ repository_name }}/actions/workflows/ci.yml/badge.svg)](https://github.com/{{ repository_namespace }}/{{ repository_name }}/actions/workflows/ci.yml) {% endif -%} -[![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)]({{ docs_url }}/) +[![documentation](https://img.shields.io/badge/docs-properdocs-708FCC.svg?style=flat)]({{ docs_url }}/) {% if not insiders or public_release -%} [![pypi version](https://img.shields.io/pypi/v/{{ python_package_distribution_name }}.svg)](https://pypi.org/project/{{ python_package_distribution_name }}/) {% endif -%} diff --git a/src/repoman/main_template/config/vscode/launch.json.jinja b/src/repoman/main_template/config/vscode/launch.json.jinja index f7640e5..1ec9267 100644 --- a/src/repoman/main_template/config/vscode/launch.json.jinja +++ b/src/repoman/main_template/config/vscode/launch.json.jinja @@ -25,7 +25,7 @@ "name": "docs", "type": "debugpy", "request": "launch", - "module": "mkdocs", + "module": "properdocs", "justMyCode": false, "args": ["serve", "-v"], "cwd": "${workspaceFolder}", diff --git a/src/repoman/main_template/make_cmds/documentation.mk b/src/repoman/main_template/make_cmds/documentation.mk index 23cede0..1f2dae7 100644 --- a/src/repoman/main_template/make_cmds/documentation.mk +++ b/src/repoman/main_template/make_cmds/documentation.mk @@ -5,17 +5,17 @@ .PHONY: docs docs: ## Build documentation @$(call i, Building documentation) - uv run mkdocs build --config-file=config/mkdocs.yml + uv run properdocs build --config-file=config/mkdocs.yml .PHONY: docs-serve docs-serve: ## Serve documentation locally @$(call i, Serving documentation) - uv run mkdocs serve --config-file=config/mkdocs.yml + uv run properdocs serve --config-file=config/mkdocs.yml .PHONY: docs-check docs-check: ## Check documentation for issues @$(call i, Checking documentation) - uv run mkdocs build --config-file=config/mkdocs.yml --strict + uv run properdocs build --config-file=config/mkdocs.yml --strict .PHONY: check-docs check-docs: docs-check ## Alias for docs-check diff --git a/src/repoman/main_template/pyproject.toml.jinja b/src/repoman/main_template/pyproject.toml.jinja index e87117e..2a82b08 100644 --- a/src/repoman/main_template/pyproject.toml.jinja +++ b/src/repoman/main_template/pyproject.toml.jinja @@ -137,8 +137,8 @@ docs = [ "mkdocs-minify-plugin>=0.8.0", "pymdown-extensions>=10.12", "mkdocs-jupyter>=0.24.8", - "mkdocs>=1.6.1", "mkdocstrings[python]>=1.0.0", "mkdocs-table-reader-plugin>=3.1.0", "mkdocs-charts-plugin>=0.0.13", + "properdocs>=1.6.7", ] diff --git a/src/repoman/main_template/{% if repository_provider == 'github' %}.github{% endif %}/workflows/docs.yml.jinja b/src/repoman/main_template/{% if repository_provider == 'github' %}.github{% endif %}/workflows/docs.yml.jinja index 34acd2c..81ec26d 100644 --- a/src/repoman/main_template/{% if repository_provider == 'github' %}.github{% endif %}/workflows/docs.yml.jinja +++ b/src/repoman/main_template/{% if repository_provider == 'github' %}.github{% endif %}/workflows/docs.yml.jinja @@ -60,7 +60,7 @@ jobs: python scripts/generate_coverage_badge.py coverage.xml docs/coverage-badge.json - name: Check docs in strict mode - run: uv run mkdocs build --config-file=config/mkdocs.yml --strict + run: uv run properdocs build --config-file=config/mkdocs.yml --strict - name: Upload Pages artifact if: {% raw %}${{ github.event_name != 'pull_request' }}{% endraw %} diff --git a/tests/test_template/test_ci.py b/tests/test_template/test_ci.py index 473a1c7..21f2af9 100644 --- a/tests/test_template/test_ci.py +++ b/tests/test_template/test_ci.py @@ -239,7 +239,9 @@ def test_template_badges_and_urls_render_for_github(tmp_path: Path) -> None: repo_url = _expected_repo_url("github", "testuser", "test-project") assert "[![ci](https://github.com/testuser/test-project/actions/workflows/ci.yml/badge.svg)]" in readme - assert f"[![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)]({docs_url}/)" in readme + assert ( + f"[![documentation](https://img.shields.io/badge/docs-properdocs-708FCC.svg?style=flat)]({docs_url}/)" in readme + ) assert "[![pypi version](https://img.shields.io/pypi/v/test-project.svg)]" in readme assert "[![license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](LICENSE)" in readme assert "[![python](https://img.shields.io/badge/python-%3E%3D3.11-blue.svg?style=flat)](#installation)" in readme @@ -280,7 +282,9 @@ def test_template_badges_and_urls_render_for_gitlab(tmp_path: Path) -> None: repo_url = _expected_repo_url("gitlab", "testuser", "test-project") assert "[![ci]" not in readme - assert f"[![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)]({docs_url}/)" in readme + assert ( + f"[![documentation](https://img.shields.io/badge/docs-properdocs-708FCC.svg?style=flat)]({docs_url}/)" in readme + ) assert "[![pypi version](https://img.shields.io/pypi/v/test-project.svg)]" in readme assert "[![license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](LICENSE)" in readme assert "[![python](https://img.shields.io/badge/python-%3E%3D3.11-blue.svg?style=flat)](#installation)" in readme @@ -323,7 +327,9 @@ def test_template_badges_and_urls_render_for_azure(tmp_path: Path) -> None: repo_url = _expected_repo_url("azure", "testuser", "test-project") assert "[![ci]" not in readme - assert f"[![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)]({docs_url}/)" in readme + assert ( + f"[![documentation](https://img.shields.io/badge/docs-properdocs-708FCC.svg?style=flat)]({docs_url}/)" in readme + ) assert "[![pypi version](https://img.shields.io/pypi/v/test-project.svg)]" in readme assert "[![license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](LICENSE)" in readme assert "[![python](https://img.shields.io/badge/python-%3E%3D3.11-blue.svg?style=flat)](#installation)" in readme