An MkDocs extension to generate documentation for Click command line applications
Project description
mkdocs-click
An MkDocs extension to generate documentation for Click command line applications.
Installation
Install from PyPI:
pip install mkdocs-click
Quickstart
Add mkdocs-click
to Markdown extensions in your mkdocs.yml
configuration:
site_name: Example
theme: readthedocs
markdown_extensions:
- mkdocs-click
Add a CLI application, e.g.:
# app/cli.py
import click
@click.group()
def cli():
"""Main entrypoint."""
@cli.command()
@click.option("-d", "--debug", help="Include debug output.")
def build(debug):
"""Build production assets."""
Add a mkdocs-click
block in your Markdown:
# CLI Reference
This page provides documentation for our command line tools.
::: mkdocs-click
:module: app.cli
:command: cli
Start the docs server:
mkdocs serve
Tada! 💫
Usage
Documenting commands
To add documentation for a command, add a mkdocs-click
block where the documentation should be inserted.
Example:
::: mkdocs-click
:module: app.cli
:command: main
For all available options, see the Block syntax.
Multi-command support
When pointed at a group (or any other multi-command), mkdocs-click
will also generate documentation for sub-commands.
This allows you to generate documentation for an entire CLI application by pointing mkdocs-click
at the root command.
Tweaking header levels
By default, mkdocs-click
generates Markdown headers starting at <h1>
for the root command section. This is generally what you want when the documentation should fill the entire page.
If you are inserting documentation within other Markdown content, you can set the :depth:
option to tweak the initial header level. Note that this applies even if you are just adding a heading.
By default it is set to 0
, i.e. headers start at <h1>
. If set to 1
, headers will start at <h2>
, and so on. Note that if you insert your own first level heading and leave depth at its default value of 0, the page will have multiple <h1>
tags, which is not compatible with themes that generate page-internal menus such as the ReadTheDocs and mkdocs-material themes.
Full command path headers
By default, mkdocs-click
outputs headers that contain the command name. For nested commands such as $ cli build all
, this also means the heading would be ## all
. This might be surprising, and may be harder to navigate at a glance for highly nested CLI apps.
If you'd like to show the full command path instead, turn on the Attribute Lists extension:
# mkdocs.yaml
markdown_extensions:
- attr_list
- mkdocs-click
mkdocs-click
will then output the full command path in headers (e.g. ## cli build all
) and permalinks (e.g. #cli-build-all
).
Note that the table of content (TOC) will still use the command name: the TOC is naturally hierarchal, so full command paths would be redundant. (This exception is why the attr_list
extension is required.)
Reference
Block syntax
The syntax for mkdocs-click
blocks is the following:
::: mkdocs-click
:module: <MODULE>
:command: <COMMAND>
:prog_name: <PROG_NAME>
:depth: <DEPTH>
:style: <STYLE>
Options:
module
: Path to the module where the command object is located.command
: Name of the command object.prog_name
: (Optional, default: same ascommand
) The name to display for the command.depth
: (Optional, default:0
) Offset to add when generating headers.style
: (Optional, default:plain
) Style for the options section. The possible choices areplain
andtable
.remove_ascii_art
: (Optional, default:False
) When docstrings begin with the escape character\b
, all text will be ignored until the next blank line is encountered.
Changelog
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog.
0.5.0 - 2021-11-19
Added
- Add ability to ignore ASCII art. (Pull #45)
Fixed
- Correctly handle default values of
None
. (Pull #41)
0.4.0 - 2021-05-12
Added
- Relax
click
version constraint. (Pull #39)
0.3.0 - 2021-02-19
Changed
--help
is now kept in options (it used to be automatically dropped). (Pull #29)
Added
- Add table formatting. (Pulls #25, #30)
- Use
:prog_name:
more consistently in usage. (Pull #24) - Allow using full command paths in headers. (Pull #36)
Fixed
- Make usage and options headings bold to improve legibility. (Pull #31)
0.2.0 - 2020-12-09
Added
- Add
:prog_name:
option to allow overriding the name of the CLI program. (Pull #8, contributed by @frankier.) - Add official support for Python 3.9. (Pull #20)
Fixed
- Properly pin
click==7.*
andmarkdown==3.*
. (Pull #19)
0.1.1 - 2020-06-05
Fixed
- Raise proper error when processing unnamed commands. (Pull #4)
0.1.0 - 2020-06-04
Initial implementation.
Added
- Add
::: mkdocs-click
block with:module:
,:command:
and:depth:
options.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file mkdocs_click-0.5.0.tar.gz
.
File metadata
- Download URL: mkdocs_click-0.5.0.tar.gz
- Upload date:
- Size: 15.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.6.0 importlib_metadata/4.8.2 pkginfo/1.8.0 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.8.12
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | a506983881da5e9405fdecc03351806661f433e1c2f81092fb05c9b93998c11a |
|
MD5 | 8702e4cced73da30af7d75022d3ecc3c |
|
BLAKE2b-256 | 915e77932b2986844b090b47dc2653ac3e7f0a474cd14edee457e31efaef5592 |
File details
Details for the file mkdocs_click-0.5.0-py3-none-any.whl
.
File metadata
- Download URL: mkdocs_click-0.5.0-py3-none-any.whl
- Upload date:
- Size: 14.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.6.0 importlib_metadata/4.8.2 pkginfo/1.8.0 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.8.12
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | ded9c09e3a7966fba8b147bbe2a3ef0b31a21072340b8c08cd8c885da57d0746 |
|
MD5 | 46508f9e97275cb4b5cdb146e9e408e2 |
|
BLAKE2b-256 | 3cbf2761828aae9b207d12115553f7682d25da3ef6f8485e02288438e4b2e397 |