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/.readthedocs.yaml b/.readthedocs.yaml index bb48e0950..4430e50ed 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,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 index 07afeadc2..d9bba4c1f 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 +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 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/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/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 = [