Skip to content

Commit

Permalink
Migrate documentation to use Markdown and MkDocs (#1397)
Browse files Browse the repository at this point in the history
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
  • Loading branch information
tleonhardt authored Dec 24, 2024
1 parent 91fd9b1 commit 9d3f227
Show file tree
Hide file tree
Showing 150 changed files with 4,704 additions and 7,221 deletions.
2 changes: 1 addition & 1 deletion .github/CODEOWNERS
Validating CODEOWNERS rules …
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
101 changes: 51 additions & 50 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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:

Expand All @@ -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
```
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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
```
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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.

Expand All @@ -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.
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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/)

Expand Down
16 changes: 8 additions & 8 deletions .github/workflows/doc.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
# Python development, test, and build
__pycache__
target
build
dist
*.egg-info
Expand Down
2 changes: 2 additions & 0 deletions .prettierignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# Markdown documentation files with non-standards syntax for mkdocstrings that Prettier should not auto-format
docs/features/initialization.md
10 changes: 10 additions & 0 deletions .prettierrc
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
{
"overrides": [
{
"files": "*.md",
"options": {
"tabWidth": 4
}
}
]
}
18 changes: 7 additions & 11 deletions .readthedocs.yaml
Original file line number Diff line number Diff line change
@@ -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:
Expand Down
9 changes: 5 additions & 4 deletions Pipfile
Original file line number Diff line number Diff line change
Expand Up @@ -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 = "*"
Expand All @@ -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]
Expand Down
6 changes: 3 additions & 3 deletions cmd2/ansi.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
Loading

0 comments on commit 9d3f227

Please sign in to comment.