Skip to main content

An MkDocs extension to generate documentation for Click command line applications

Project description

mkdocs-click

Tests Python versions Package version

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 as command) 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 are plain and table.
  • 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.* and markdown==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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mkdocs_click-0.5.0.tar.gz (15.6 kB view details)

Uploaded Source

Built Distribution

mkdocs_click-0.5.0-py3-none-any.whl (14.6 kB view details)

Uploaded Python 3

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

Hashes for mkdocs_click-0.5.0.tar.gz
Algorithm Hash digest
SHA256 a506983881da5e9405fdecc03351806661f433e1c2f81092fb05c9b93998c11a
MD5 8702e4cced73da30af7d75022d3ecc3c
BLAKE2b-256 915e77932b2986844b090b47dc2653ac3e7f0a474cd14edee457e31efaef5592

See more details on using hashes here.

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

Hashes for mkdocs_click-0.5.0-py3-none-any.whl
Algorithm Hash digest
SHA256 ded9c09e3a7966fba8b147bbe2a3ef0b31a21072340b8c08cd8c885da57d0746
MD5 46508f9e97275cb4b5cdb146e9e408e2
BLAKE2b-256 3cbf2761828aae9b207d12115553f7682d25da3ef6f8485e02288438e4b2e397

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page