Migrate documentation to use Markdown and MkDocs (#1397)

Migrate documentation to use [MkDocs](https://www.mkdocs.org/) with the [Material Theme](https://squidfunk.github.io/mkdocs-material/) for the build. Replaced all use of reStructuredText with Markdown and all use of Sphinx with MkDocs.

TODO:

- [x] Create MkDocs Material theme basic setup and configuration
- [x] Translate reStructuredText docs to Markdown using `pandoc`
- [x] Verify MkDocs build and serve are working 
- [x] Delete Sphinx stuff and make sure GitHub Actions doc build is working 
- [x] Finish correcting basic translation errors 
- [x] Get automated API documentation using [mkdocstrings](https://mkdocstrings.github.io/) working nicely
- [x] Figure out how to do autodoc references using `mkdocstring`
- [x] Final cleanup check of markdown
- [x] Make [recommended tweaks](https://docs.readthedocs.io/en/stable/intro/mkdocs.html) for hosting docs on ReadTheDocs
- [x] Add example of using [mermaid](https://mermaid.js.org/) to embed diagrams in `scripting.md`
- [x] Verify ReadTheDocs build is working properly

Closes #1396

Author: tleonhardt

.github/CODEOWNERS

@@ -41,7 +41,7 @@ cmd2/table_creator.py      @kmvanbrunt
 cmd2/transcript.py         @kotfu
 cmd2/utils.py              @tleonhardt @kotfu @kmvanbrunt
 
-# Sphinx documentation
+# Documentation
 docs/*                  @tleonhardt @kotfu
 
 # Examples

.github/CONTRIBUTING.md

@@ -11,12 +11,12 @@ We welcome pull requests from cmd2 users and seasoned Python developers alike! F
 
 Remember to feel free to ask for help by leaving a comment within the Issue.
 
-Working on your first pull request? You can learn how from the 
+Working on your first pull request? You can learn how from the
 [GitHub Docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).
 
 ###### If you've found a bug that is not on the board, [follow these steps](../README.md#found-a-bug).
 
---------------------------------------------------------------------------------
+---
 
 ## Contribution guidelines
 
@@ -46,39 +46,38 @@ The tables below list all prerequisites along with the minimum required version
 
 #### Prerequisites to run cmd2 applications
 
-| Prerequisite                                         | Minimum Version |
-|------------------------------------------------------|-----------------|
-| [python](https://www.python.org/downloads/)          | `3.8`           |
-| [pyperclip](https://github.com/asweigart/pyperclip)  | `1.8.2`         |
-| [wcwidth](https://pypi.python.org/pypi/wcwidth)      | `0.2.12`        |
+| Prerequisite                                        | Minimum Version |
+| --------------------------------------------------- | --------------- |
+| [python](https://www.python.org/downloads/)         | `3.8`           |
+| [pyperclip](https://github.com/asweigart/pyperclip) | `1.8.2`         |
+| [wcwidth](https://pypi.python.org/pypi/wcwidth)     | `0.2.12`        |
 
 #### Additional prerequisites to build and publish cmd2
 
 | Prerequisite                                             | Minimum Version |
-|----------------------------------------------------------|-----------------|
+| -------------------------------------------------------- | --------------- |
 | [build](https://pypi.org/project/build/)                 | `1.2.2`         |
 | [setuptools](https://pypi.org/project/setuptools/)       | `72.1.0`        |
 | [setuptools-scm](https://github.com/pypa/setuptools-scm) | `8.0.4`         |
 | [twine](https://github.com/pypa/twine)                   | `5.1.1`         |
 
 #### Additional prerequisites for developing cmd2
 
-| Prerequisite                                                         | Minimum Version | Purpose                    |
-|----------------------------------------------------------------------|-----------------|----------------------------|
-| [codecov](http://doc.pytest.org/en/latest/)                          | `2.1.13`        | Cover coverage reporting   |
-| [doc8](https://github.com/PyCQA/doc8)                                | `1.1.2`         | Sphinx style checker       |
-| [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      |
-| [sphinx](https://www.sphinx-doc.org/en/master/)                      | `8.1.3`         | Documentation              |
-| [sphinx-autobuild](hhttps://pypi.org/project/sphinx-autobuild/)      | `2024.10.3`     | Rebuild docs on changes    |
-| [sphinx-rtd-theme](https://github.com/readthedocs/sphinx_rtd_theme ) | `3.0.1`         | Sphinx theme for RTD       |
-| [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                |
+| [griffe_typingdoc](https://github.com/mkdocstrings/griffe-typingdoc)                       | `0.2.7`         | mkdocstrings extension for typing |
+| [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         |
 
 If Python is already installed in your machine, run the following commands to validate the versions:
 
@@ -89,11 +88,12 @@ $ pip freeze | grep pyperclip
 
 If your versions are lower than the prerequisite versions, you should update.
 
-If you do not already have Python installed on your machine, we recommend using [uv](https://github.com/astral-sh/uv)     
+If you do not already have Python installed on your machine, we recommend using [uv](https://github.com/astral-sh/uv)  
 for all of your Python needs because it is extremely fast, meets all Python installation and packaging needs, and works
-on all platforms (Windows, Mac, and Linux).  You can install `uv` using instructions at the link above.
+on all platforms (Windows, Mac, and Linux). You can install `uv` using instructions at the link above.
 
 You can then install multiple versions of Python using `uv` like so:
+
 ```sh
 uv python install 3.10 3.11 3.12 3.13
 ```
@@ -147,31 +147,31 @@ Do this prior to every time you create a branch for a PR:
 1. Make sure you are on the `master` branch
 
 > ```sh
-  > $ git status
-  > On branch master
-  > Your branch is up-to-date with 'origin/master'.
-  > ```
+> $ git status
+> On branch master
+> Your branch is up-to-date with 'origin/master'.
+> ```
 
 > If your aren't on `master`, resolve outstanding files and commits and checkout the `master` branch
 
 > ```sh
-  > $ git checkout master
-  > ```
+> $ git checkout master
+> ```
 
 2. Do a pull with rebase against `upstream`
 
 > ```sh
-  > $ git pull --rebase upstream master
-  > ```
+> $ git pull --rebase upstream master
+> ```
 
 > This will pull down all of the changes to the official master branch, without making an additional commit in your
 > local repo.
 
 3. (_Optional_) Force push your updated master branch to your GitHub fork
 
 > ```sh
-  > $ git push origin master --force
-  > ```
+> $ git push origin master --force
+> ```
 
 > This will overwrite the master branch of your fork.
 
@@ -213,8 +213,8 @@ package from the source.
 
 `cmd2` has support for using [uv](https://github.com/astral-sh/uv) for development.
 
-`uv` is single tool to replace `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, `twine`, `virtualenv`, and more. `cmd2` 
-contains configuration for using `uv` in it's `pyproject.toml` file  which  makes it extremely easy to setup a `cmd2` 
+`uv` is single tool to replace `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, `twine`, `virtualenv`, and more. `cmd2`
+contains configuration for using `uv` in it's `pyproject.toml` file which makes it extremely easy to setup a `cmd2`
 development environment using `uv`.
 
 To create a virtual environment and install everything needed for `cmd2` development using `uv`, do the following
@@ -238,6 +238,7 @@ uv run examples/basic.py
 ```
 
 Alternatively you can activate the virtual environment using the OS-specific command such as this on Linux or macOS:
+
 ```sh
 source .venv/bin/activate
 ```
@@ -316,7 +317,7 @@ 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
-Sphinx documentation and make sure your changes look good:
+MkDocs documentation and make sure your changes look good:
 
 ```sh
 $ uv inv docs
@@ -337,7 +338,7 @@ served (usually [http://localhost:8000](http://localhost:8000)).
 ### Code Quality Checks
 
 You should have some sort of [PEP 8](https://www.python.org/dev/peps/pep-0008/)-based linting running in your editor or
-IDE or at the command line before you commit code.  `cmd2` uses [ruff](https://github.com/astral-sh/ruff) as part of
+IDE or at the command line before you commit code. `cmd2` uses [ruff](https://github.com/astral-sh/ruff) as part of
 its continuous integration (CI) process for both linting and auto-formatting.
 
 > Please do not ignore any linting errors in code you write or modify, as they are meant to **help** you and to ensure a
@@ -440,7 +441,7 @@ nothing to commit, working directory clean
    any outstanding files/commits and checkout master `git checkout master`
 
 2. Create a branch off of `master` with git: `git checkout -B
-    branch/name-here` **Note:** Branch naming is important. Use a name like
+branch/name-here` **Note:** Branch naming is important. Use a name like
    `fix/short-fix-description` or `feature/short-feature-description`. Review
    the [Contribution Guidelines](#contribution-guidelines) for more detail.
 
@@ -449,7 +450,7 @@ nothing to commit, working directory clean
 4. Check your `git status` to see unstaged files
 
 5. Add your edited files: `git add path/to/filename.ext` You can also do: `git
-    add .` to add all unstaged files. Take care, though, because you can
+add .` to add all unstaged files. Take care, though, because you can
    accidentally add files you don't want added. Review your `git status` first.
 
 6. Commit your edits: `git commit -m "Brief description of commit"`. Do not add the issue number in the commit message.
@@ -482,17 +483,17 @@ how to do it.
 4. The title (also called the subject) of your PR should be descriptive of your
    changes and succinctly indicate what is being fixed
 
-    - **Do not add the issue number in the PR title or commit message**
+   - **Do not add the issue number in the PR title or commit message**
 
-    - Examples: `Add test cases for Unicode support`; `Correct typo in overview documentation`
+   - Examples: `Add test cases for Unicode support`; `Correct typo in overview documentation`
 
 5. In the body of your PR include a more detailed summary of the changes you
    made and why
 
-    - If the PR is meant to fix an existing bug/issue, then, at the end of
-      your PR's description, append the keyword `closes` and #xxxx (where xxxx
-      is the issue number). Example: `closes #1337`. This tells GitHub to
-      close the existing issue if the PR is merged.
+   - If the PR is meant to fix an existing bug/issue, then, at the end of
+     your PR's description, append the keyword `closes` and #xxxx (where xxxx
+     is the issue number). Example: `closes #1337`. This tells GitHub to
+     close the existing issue if the PR is merged.
 
 6. Indicate what local testing you have done (e.g. what OS and version(s) of Python did you run the
    unit test suite with)
@@ -632,8 +633,8 @@ mostly automated. The manual steps are all git operations. Here's the checklist:
 1. Make sure all the unit tests pass with `invoke pytest` or `py.test`
 1. Make sure latest year in `LICENSE` matches current year
 1. Make sure `CHANGELOG.md` describes the version and has the correct release date
-1. Add a git tag representing the version number using ``invoke tag x.y.z``
-    * Where x, y, and z are all small non-negative integers
+1. Add a git tag representing the version number using `invoke tag x.y.z`
+   - Where x, y, and z are all small non-negative integers
 1. (Optional) Run `invoke pypi-test` to clean, build, and upload a new release to [Test PyPi](https://test.pypi.org)
 1. Run `invoke pypi` to clean, build, and upload a new release to [PyPi](https://pypi.org/)
 

.github/workflows/doc.yml

@@ -2,7 +2,7 @@
 # https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions
 name: Doc
 
-on: [ push, pull_request, workflow_dispatch ]
+on: [push, pull_request, workflow_dispatch]
 
 permissions:
   contents: read
@@ -11,21 +11,21 @@ jobs:
   doc:
     strategy:
       matrix:
-        os: [ ubuntu-latest ]
-        python-version: [ "3.12" ]
+        os: [ubuntu-latest]
+        python-version: ["3.12"]
       fail-fast: false
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v4  # https://github.com/actions/checkout
+      - uses: actions/checkout@v4 # https://github.com/actions/checkout
         with:
           # Only a single commit is fetched by default, for the ref/SHA that triggered the workflow.
           # Set fetch-depth: 0 to fetch all history for all branches and tags.
           fetch-depth: 0 # Needed for setuptools_scm to work correctly
       - name: Set up Python
-        uses: actions/setup-python@v5  # https://github.com/actions/setup-python
+        uses: actions/setup-python@v5 # https://github.com/actions/setup-python
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install python prerequisites
-        run: pip install -U --user pip setuptools setuptools-scm sphinx sphinx-autobuild sphinx-rtd-theme . plugins/ext_test
-      - name: Sphinx documentation build
-        run: python -m sphinx -M html docs docs/_build -nvWT
+        run: pip install -U --user pip setuptools setuptools-scm griffe_typingdoc mkdocs-include-markdown-plugin mkdocs-macros-plugin mkdocs-material mkdocstrings[python] . plugins/ext_test
+      - name: MkDocs documentation build
+        run: mkdocs build

.gitignore

@@ -1,5 +1,6 @@
 # Python development, test, and build
 __pycache__
+target
 build
 dist
 *.egg-info

.prettierignore

@@ -0,0 +1,2 @@
+# Markdown documentation files with non-standards syntax for mkdocstrings that Prettier should not auto-format
+docs/features/initialization.md

.prettierrc

@@ -0,0 +1,10 @@
+{
+    "overrides": [
+      {
+        "files": "*.md",
+        "options": {
+          "tabWidth": 4
+        }
+      }
+    ]
+  }

.readthedocs.yaml

@@ -1,22 +1,18 @@
-# Read the Docs configuration file for Sphinx projects
-# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+# Read the Docs configuration file for MkDocs projects
+# See https://docs.readthedocs.io/en/stable/intro/mkdocs.html for details
 
 # Required
 version: 2
 
 # Set the OS, Python version and other tools you might need
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
-    python: "3.12"
+    python: "3"
 
-# Build documentation in the "docs/" directory with Sphinx
-sphinx:
-  configuration: docs/conf.py
-  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
-  # builder: "dirhtml"
-  # Fail on all warnings to avoid broken references
-  # fail_on_warning: true
+# Build documentation in the "docs/" directory with MkDocs
+mkdocs:
+  configuration: mkdocs.yml
 
 # Optionally build your docs in additional formats such as PDF and ePub
 # formats:

Pipfile

@@ -13,8 +13,8 @@ build = "*"
 cmd2 = { editable = true, path = "." }
 cmd2_ext_test = { editable = true, path = "plugins/ext_test" }
 codecov = "*"
-doc8 = "*"
 gnureadline = { version = "*", sys_platform = "== 'darwin'" }
+griffe-typingdoc = "*"
 invoke = "*"
 ipython = "*"
 mypy = "*"
@@ -24,9 +24,10 @@ pytest-cov = "*"
 pytest-mock = "*"
 ruff = "*"
 setuptools-scm = "*"
-sphinx = "*"
-sphinx-autobuild = "*"
-sphinx-rtd-theme = "*"
+mkdocs-include-markdown-plugin = "*"
+mkdocs-macros-plugin = "*"
+mkdocs-material = "*"
+mkdocstrings[python] = "*"
 twine = ">=1.11"
 
 [pipenv]

cmd2/ansi.py

@@ -1043,13 +1043,13 @@ def style(
 # These can be altered to suit an application's needs and only need to be a
 # function with the following structure: func(str) -> str
 style_success = functools.partial(style, fg=Fg.GREEN)
-"""Partial function supplying arguments to :meth:`cmd2.ansi.style()` which colors text to signify success"""
+"""Partial function supplying arguments to [cmd2.ansi.style][] which colors text to signify success"""
 
 style_warning = functools.partial(style, fg=Fg.LIGHT_YELLOW)
-"""Partial function supplying arguments to :meth:`cmd2.ansi.style()` which colors text to signify a warning"""
+"""Partial function supplying arguments to [cmd2.ansi.style][] which colors text to signify a warning"""
 
 style_error = functools.partial(style, fg=Fg.LIGHT_RED)
-"""Partial function supplying arguments to :meth:`cmd2.ansi.style()` which colors text to signify an error"""
+"""Partial function supplying arguments to [cmd2.ansi.style][] which colors text to signify an error"""
 
 
 def async_alert_str(*, terminal_columns: int, prompt: str, line: str, cursor_offset: int, alert_msg: str) -> str: