From 3ba9103675bb707919b36dbfff1dbf72de52ed7b Mon Sep 17 00:00:00 2001 From: Todd Leonhardt Date: Sun, 21 Dec 2025 03:04:57 -0500 Subject: [PATCH 1/2] Eliminate use of the include-markdown plugin for MkDocs Replace it's use with simply refactoring some of the documentaiton and also using the pymdown.snippets extension which is more reliably supported by MkDocs. This is based in part on real-world problems encountered using the include-markdown problem with various other plugins and with migrating to Zensical. --- .github/CONTRIBUTING.md | 27 +++++++++++------------ docs/examples/examples.md | 4 +--- docs/index.md | 45 +++++++++++++++++---------------------- mkdocs.yml | 9 ++++---- pyproject.toml | 2 -- 5 files changed, 37 insertions(+), 50 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 3467d5828..1e56496df 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -93,20 +93,19 @@ 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 | -| [invoke](https://www.pyinvoke.org/) | `2.2.0` | Command automation | -| [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-include-markdown-plugin](https://pypi.org/project/mkdocs-include-markdown-plugin/) | `7.1.2` | MkDocs Plugin include MkDn | -| [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 | +| [invoke](https://www.pyinvoke.org/) | `2.2.0` | Command automation | +| [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 | If Python is already installed in your machine, run the following commands to validate the versions: diff --git a/docs/examples/examples.md b/docs/examples/examples.md index 1a14e7fa3..965e775ae 100644 --- a/docs/examples/examples.md +++ b/docs/examples/examples.md @@ -1,5 +1,3 @@ # List of cmd2 examples -{% - include-markdown "../../examples/README.md" -%} +--8<-- "docs/../examples/README.md" diff --git a/docs/index.md b/docs/index.md index ccb9dfd99..460f72810 100644 --- a/docs/index.md +++ b/docs/index.md @@ -25,46 +25,39 @@ app = App() app.cmdloop() ``` - +## Getting Started -{% - include-markdown "./overview/index.md" -%} +See the [Getting Started](overview/index.md) section for info on how to get started building a +`cmd2` application. - +## Migrating from cmd2 -{% - include-markdown "./migrating/index.md" -%} +See the [Migrating from cmd2](migrating/index.md) section for info on how to migrate a `cmd` +application to `cmd2`. ## Features -{% - include-markdown "./features/index.md" - start="" - end="" -%} +See the [Features](features/index.md) section for a detailed guide to the features available within +`cmd2`. ## Examples -{% - include-markdown "./examples/index.md" - start="" - end="" -%} +See the [Examples](examples/index.md) section for various examples of using `cmd2`. ## Mixins -{% - include-markdown "./mixins/index.md" - start="" - end="" -%} +See the [Mixins](mixins/index.md) section for info on how to extend `cmd2` using mixins. -## [Testing](testing.md) +## Testing -## [API Reference](api/index.md) +See the [Testing](testing.md) section for special considerations when writing unit or integration +tests for a `cmd2` application. + +## API Reference + +See the [API Reference](api/index.md) for detailed information on the public API of `cmd2`. ## Meta -[Documentation Conventions](doc_conventions.md) +See the [Documentation Conventions](doc_conventions.md) for info on conventions used in this +documentation. diff --git a/mkdocs.yml b/mkdocs.yml index 1ff95631a..26d100bcd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -60,10 +60,6 @@ theme: plugins: - search - git-revision-date-localized - - include-markdown: - preserve_includer_indent: true - dedent: true - comments: false - macros: render_by_default: false on_error_fail: true @@ -121,6 +117,9 @@ markdown_extensions: - pymdownx.inlinehilite - pymdownx.keys - pymdownx.smartsymbols + - pymdownx.snippets: + base_path: [".", "docs", "docs/overview"] + check_paths: true - pymdownx.superfences: custom_fences: - name: mermaid @@ -137,7 +136,7 @@ validation: absolute_links: info links: not_found: warn - absolute_links: info + absolute_links: ignore unrecognized_links: info not_in_nav: | diff --git a/pyproject.toml b/pyproject.toml index 6da2292e8..743ba822d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -45,7 +45,6 @@ dev = [ "invoke>=2.2.1", "ipython>=8.23", "mkdocs-git-revision-date-localized-plugin>=1.5", - "mkdocs-include-markdown-plugin>=7", "mkdocs-macros-plugin>=1.2", "mkdocs-material>=9.7.1", "mkdocstrings[python]>=1", @@ -60,7 +59,6 @@ dev = [ docs = [ "black>=25", "mkdocs-git-revision-date-localized-plugin>=1.5", - "mkdocs-include-markdown-plugin>=7", "mkdocs-macros-plugin>=1.2", "mkdocs-material>=9.7.1", "mkdocstrings[python]>=1", From 8cf50b925ef9521150742733b6afc8862634b34e Mon Sep 17 00:00:00 2001 From: Todd Leonhardt Date: Sun, 21 Dec 2025 03:08:31 -0500 Subject: [PATCH 2/2] Removed extra base_path from pymdown.snippets extension --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 26d100bcd..fb0b7611f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -118,7 +118,7 @@ markdown_extensions: - pymdownx.keys - pymdownx.smartsymbols - pymdownx.snippets: - base_path: [".", "docs", "docs/overview"] + base_path: [".", "docs"] check_paths: true - pymdownx.superfences: custom_fences: