mkdocs-click

An MkDocs extension to generate documentation for Click command line applications.

Installation

This package is not available on PyPI yet, but you can install it from git:

pip install git+https://github.com/DataDog/mkdocs-click.git

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.

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.

Reference

Block syntax

The syntax for mkdocs-click blocks is the following:

::: mkdocs-click
    :module: <MODULE>
    :command: <COMMAND>
    :depth: <DEPTH>

Options:

• module: path to the module where the command object is located.
• command: name of the command object.
• depth: (Optional, default: 0) Offset to add when generating headers.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog.

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.