diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 3467d582..1e56496d 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 1a14e7fa..965e775a 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 ccb9dfd9..460f7281 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 1ff95631..fb0b7611 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"] + 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 6da2292e..743ba822 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",