Migrate documentation to use Zensical instead of MkDocs (#1557)

tleonhardt · web-flow · commit be4a177c72d8 · 2026-01-20T19:07:57.000-05:00
* Migrate documentation to use Zensical instead of MkDocs

For now leave the configuration in mkdocs.yml.

TODO later: Migrate configuration to zensical.toml

* Switch .readthedocs.yaml to use uv

* Fix .readthedocs.yaml since uv --frozen requires a uv lock file

* Use correct zensical output directory for RTD

* Add .github/CODEOWNERS to .prettierignore

Also:
- "make docs" now also automatically opens site in default browser
- Made a few small simplifications in mkdocs.yml
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -93,18 +93,17 @@ for a list of dependencies needed for building `cmd2`.
 See the `dev` list under the `[dependency-groups]` heading in [pyproject.toml](../pyproject.toml)
 for a list of dependencies needed for building `cmd2`.
 
-| Prerequisite                                                         | Minimum Version | Purpose                          |
-| -------------------------------------------------------------------- | --------------- | -------------------------------- |
-| [codecov](http://doc.pytest.org/en/latest/)                          | `2.1.13`        | Cover coverage reporting         |
-| [mypy](https://mypy-lang.org/)                                       | `1.13.0`        | Static type checker              |
-| [pytest](https://docs.pytest.org/en/stable/)                         | `3.0.6`         | Unit and integration tests       |
-| [pytest-cov](http://doc.pytest.org/en/latest/)                       | `6.0.0`         | Pytest code coverage             |
-| [pytest-mock](https://pypi.org/project/pytest-mock/)                 | `3.14.0`        | Pytest mocker fixture            |
-| [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) | `1.3.7`         | MkDocs Plugin for macros         |
-| [mkdocs-material](https://squidfunk.github.io/mkdocs-material/)      | `9.5.49`        | Documentation                    |
-| [mkdocstrings[python]](https://mkdocstrings.github.io/)              | `0.27.0`        | MkDocs Plugin for Python AutoDoc |
-| [ruff](https://github.com/astral-sh/ruff)                            | `0.7.3`         | Fast linter and formatter        |
-| [uv](https://github.com/astral-sh/uv)                                | `0.5.1`         | Python package management        |
+| Prerequisite                                            | Minimum Version | Purpose                            |
+| ------------------------------------------------------- | --------------- | ---------------------------------- |
+| [codecov](http://doc.pytest.org/en/latest/)             | `2.1.13`        | Cover coverage reporting           |
+| [mypy](https://mypy-lang.org/)                          | `1.13.0`        | Static type checker                |
+| [pytest](https://docs.pytest.org/en/stable/)            | `3.0.6`         | Unit and integration tests         |
+| [pytest-cov](http://doc.pytest.org/en/latest/)          | `6.0.0`         | Pytest code coverage               |
+| [pytest-mock](https://pypi.org/project/pytest-mock/)    | `3.14.0`        | Pytest mocker fixture              |
+| [mkdocstrings[python]](https://mkdocstrings.github.io/) | `0.27.0`        | Zensical plugin for Python AutoDoc |
+| [ruff](https://github.com/astral-sh/ruff)               | `0.7.3`         | Fast linter and formatter          |
+| [uv](https://github.com/astral-sh/uv)                   | `0.5.1`         | Python package management          |
+| [Zensical](https://github.com/zensical/zensical)        | `0.0.17`        | Markdown-based documentation       |
 
 If Python is already installed in your machine, run the following commands to validate the versions:
 
@@ -351,8 +350,8 @@ are primarily related to continuous integration and release deployment.
 
 #### Changes to the documentation files
 
-If you made changes to any file in the `/docs` directory, you need to build the MkDocs documentation
-and make sure your changes look good:
+If you made changes to any file in the `/docs` directory, you need to build the Zensical
+documentation and make sure your changes look good:
 
 ```sh
 $ make docs-test
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -27,5 +27,5 @@ jobs:
           python-version: "3.14"
       - name: Install the project
         run: uv sync --group docs
-      - name: Check if the MkDocs documentation can be built
-        run: uv run mkdocs build -s
+      - name: Check if the Zensical documentation can be built
+        run: uv run zensical build -s
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -1,5 +1,5 @@
-# Read the Docs configuration file for MkDocs projects
-# See https://docs.readthedocs.io/en/stable/intro/mkdocs.html for details
+# Read the Docs configuration file for Zensical projects
+# See https://docs.readthedocs.com/platform/stable/intro/zensical.html for details
 
 # Required
 version: 2
@@ -10,17 +10,23 @@ version: 2
 #   - epub
 formats: all
 
-# Build documentation in the "docs/" directory with MkDocs
-mkdocs:
-  configuration: mkdocs.yml
-
 # Set the OS, Python version and other tools you might need
 build:
   os: ubuntu-24.04
   tools:
-    python: "3.13"
+    python: latest
   jobs:
+    pre_create_environment:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+    create_environment:
+      - uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
     install:
-      - pip install .
-      - pip install dependency-groups
-      - pip-install-dependency-groups docs
+      - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --group docs
+    build:
+      html:
+        - zensical build
+    post_build:
+      - mkdir -p $READTHEDOCS_OUTPUT/html/
+      - cp --recursive build/html/* $READTHEDOCS_OUTPUT/html/
diff --git a/Makefile b/Makefile
@@ -40,11 +40,11 @@ test: ## Test the code with pytest.
 
 .PHONY: docs-test
 docs-test: ## Test if documentation can be built without warnings or errors
-	@uv run mkdocs build -s
+	@uv run zensical build -s
 
 .PHONY: docs
-docs: ## Build and serve the documentation
-	@uv run mkdocs serve
+docs: ## Build and serve the documentation (and open in default browser)
+	@uv run zensical serve -o
 
 .PHONY: build
 build: clean-build ## Build wheel file
diff --git a/docs/doc_conventions.md b/docs/doc_conventions.md
@@ -62,7 +62,7 @@ See the [Links](https://www.markdownguide.org/basic-syntax/) Markdown syntax doc
 
 ## API Documentation
 
-The API documentation is mostly pulled from docstrings in the source code using the MkDocs
+The API documentation is mostly pulled from docstrings in the source code using the Zensical
 [mkdocstrings](https://mkdocstrings.github.io/) plugin.
 
 When using `mkdocstrings`, it must be preceded by a blank line before and after, i.e.:
diff --git a/docs/javascripts/readthedocs.js b/docs/javascripts/readthedocs.js
@@ -1,5 +1,5 @@
 document.addEventListener("DOMContentLoaded", function (event) {
-  // Trigger Read the Docs' search addon instead of Material MkDocs default
+  // Trigger Read the Docs' search addon instead of Zensical default
   document.querySelector(".md-search__input").addEventListener("focus", (e) => {
     const event = new CustomEvent("readthedocs-search-show");
     document.dispatchEvent(event);
diff --git a/pyproject.toml b/pyproject.toml
@@ -40,11 +40,8 @@ dependencies = [
 [dependency-groups]
 build = ["build>=1.2.2", "setuptools>=80.7.1", "setuptools-scm>=9.2"]
 dev = [
-    "black>=25",
     "codecov>=2.1",
     "ipython>=8.23",
-    "mkdocs-git-revision-date-localized-plugin>=1.5",
-    "mkdocs-material>=9.7.1",
     "mkdocstrings[python]>=1",
     "mypy>=1.13",
     "pre-commit>=3",
@@ -53,14 +50,13 @@ dev = [
     "pytest-mock>=3.14.1",
     "ruff>=0.14.10",
     "uv-publish>=1.3",
+    "zensical>=0.0.17",
 ]
 docs = [
-    "black>=25",
-    "mkdocs-git-revision-date-localized-plugin>=1.5",
-    "mkdocs-material>=9.7.1",
     "mkdocstrings[python]>=1",
     "setuptools>=80.7.1",
     "setuptools_scm>=8",
+    "zensical>=0.0.17",
 ]
 quality = ["pre-commit>=3"]
 test = [
