From 7c20c807c0a65589941645e01093eac70574e633 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt Date: Mon, 19 Jan 2026 20:25:41 -0500 Subject: [PATCH 1/5] Migrate documentation to use Zensical instead of MkDocs For now leave the configuration in mkdocs.yml. TODO later: Migrate configuration to zensical.toml --- .github/CONTRIBUTING.md | 27 +++++++++++++-------------- .github/workflows/docs.yml | 4 ++-- .prettierignore | 2 +- .readthedocs.yaml | 16 +++++++++------- Makefile | 4 ++-- docs/doc_conventions.md | 2 +- docs/features/argument_processing.md | 4 ++-- docs/javascripts/readthedocs.js | 2 +- docs/migrating/minimum.md | 8 ++++---- pyproject.toml | 8 ++------ 10 files changed, 37 insertions(+), 40 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 688e24dd6..e2524d74f 100644 --- 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 index dd00a29f9..964878ee9 100644 --- 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/.prettierignore b/.prettierignore index d6e44c5a2..3c56d10e4 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,2 +1,2 @@ -# Markdown documentation files with non-standards syntax for mkdocstrings that Prettier should not auto-format +# Markdown documentation files with non-standard syntax for mkdocstrings that Prettier should not auto-format docs/features/initialization.md diff --git a/.readthedocs.yaml b/.readthedocs.yaml index bb48e0950..5d16e9a63 100644 --- 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,19 @@ 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: install: - pip install . - pip install dependency-groups - pip-install-dependency-groups docs + build: + html: + - zensical build + post_build: + - mkdir -p $READTHEDOCS_OUTPUT/html/ + - cp --recursive site/* $READTHEDOCS_OUTPUT/html/ diff --git a/Makefile b/Makefile index 07afeadc2..f384247f3 100644 --- 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 + @uv run zensical serve .PHONY: build build: clean-build ## Build wheel file diff --git a/docs/doc_conventions.md b/docs/doc_conventions.md index e03e128b6..9981b75be 100644 --- 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/features/argument_processing.md b/docs/features/argument_processing.md index 4c9bf4629..00a9b94c6 100644 --- a/docs/features/argument_processing.md +++ b/docs/features/argument_processing.md @@ -27,8 +27,8 @@ example to learn more about how to use the various `cmd2` argument processing de `cmd2` provides the following [decorators](../api/decorators.md) for assisting with parsing arguments passed to commands: -- `cmd2.decorators.with_argparser` -- `cmd2.decorators.with_argument_list` +- [cmd2.decorators.with_argparser][] +- [cmd2.decorators.with_argument_list][] All of these decorators accept an optional **preserve_quotes** argument which defaults to `False`. Setting this argument to `True` is useful for cases where you are passing the arguments to another diff --git a/docs/javascripts/readthedocs.js b/docs/javascripts/readthedocs.js index cfa8491e0..b32788054 100644 --- 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/docs/migrating/minimum.md b/docs/migrating/minimum.md index 6dfb6b269..1fca3a16b 100644 --- a/docs/migrating/minimum.md +++ b/docs/migrating/minimum.md @@ -1,9 +1,9 @@ # Minimum Required Changes -[cmd2.Cmd][] subclasses [cmd.Cmd](https://docs.python.org/3/library/cmd.html#cmd.Cmd) from the -standard library, and overrides all of the methods other than `Cmd.emptyline` (`cmd2` never calls -this method). Most apps based on the standard library can be migrated to `cmd2` in just a couple of -minutes. +[cmd2.Cmd][] provides all of the same public methods and fields of +[cmd.Cmd](https://docs.python.org/3/library/cmd.html#cmd.Cmd) from the standard library other than +`Cmd.emptyline` (`cmd2` never calls this method). Most apps based on the standard library can be +migrated to `cmd2` in just a couple of minutes. ## Import and Inheritance diff --git a/pyproject.toml b/pyproject.toml index 65d313f9e..06c016965 100644 --- 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 = [ From 16335dcc5b0a352060f7d70159df9c84aea421c2 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt Date: Mon, 19 Jan 2026 20:42:17 -0500 Subject: [PATCH 2/5] Switch .readthedocs.yaml to use uv --- .readthedocs.yaml | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 5d16e9a63..ee1a83ea2 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -16,10 +16,14 @@ build: tools: 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 --frozen --group docs build: html: - zensical build From f069637dec0b466e2084f4730e38c6048d11a2e3 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt Date: Mon, 19 Jan 2026 20:44:22 -0500 Subject: [PATCH 3/5] Fix .readthedocs.yaml since uv --frozen requires a uv lock file --- .readthedocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index ee1a83ea2..774e6ce17 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -23,7 +23,7 @@ build: create_environment: - uv venv "${READTHEDOCS_VIRTUALENV_PATH}" install: - - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --frozen --group docs + - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --group docs build: html: - zensical build From f7646986125fd8d7f514a0748c56895f240a6ce7 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt Date: Mon, 19 Jan 2026 20:49:36 -0500 Subject: [PATCH 4/5] Use correct zensical output directory for RTD --- .readthedocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 774e6ce17..4430e50ed 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -29,4 +29,4 @@ build: - zensical build post_build: - mkdir -p $READTHEDOCS_OUTPUT/html/ - - cp --recursive site/* $READTHEDOCS_OUTPUT/html/ + - cp --recursive build/html/* $READTHEDOCS_OUTPUT/html/ From 18fb4f01361a0f485c9b30a57daafcd3ba7a6186 Mon Sep 17 00:00:00 2001 From: Todd Leonhardt Date: Mon, 19 Jan 2026 21:58:51 -0500 Subject: [PATCH 5/5] Add .github/CODEOWNERS to .prettierignore Also: - "make docs" now also automatically opens site in default browser - Made a few small simplifications in mkdocs.yml --- .prettierignore | 3 +++ Makefile | 4 ++-- mkdocs.yml | 10 +++++----- 3 files changed, 10 insertions(+), 7 deletions(-) diff --git a/.prettierignore b/.prettierignore index 3c56d10e4..788ac0474 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,2 +1,5 @@ +# File is nicely lined up +.github/CODEOWNERS + # Markdown documentation files with non-standard syntax for mkdocstrings that Prettier should not auto-format docs/features/initialization.md diff --git a/Makefile b/Makefile index f384247f3..d9bba4c1f 100644 --- a/Makefile +++ b/Makefile @@ -43,8 +43,8 @@ docs-test: ## Test if documentation can be built without warnings or errors @uv run zensical build -s .PHONY: docs -docs: ## Build and serve the documentation - @uv run zensical 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/mkdocs.yml b/mkdocs.yml index bd5a9a911..12d951a92 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -140,11 +140,11 @@ not_in_nav: | nav: - Home: index.md - Getting Started: - - Overview: overview/index.md - - Installation Instructions: overview/installation.md - - Integrate cmd2 Into Your Project: overview/integrating.md - - Alternatives: overview/alternatives.md - - Resources: overview/resources.md + - overview/index.md + - overview/installation.md + - overview/integrating.md + - overview/alternatives.md + - overview/resources.md - Migrating From cmd: - migrating/index.md - migrating/why.md