mkdocs-click

一个用于生成Click命令行应用程序文档的MkDocs扩展。

最初由Datadog开发。

安装

从PyPI安装

pip install mkdocs-click

快速入门

将mkdocs-click添加到mkdocs.yml配置中的Markdown扩展

site_name: Example
theme: readthedocs

markdown_extensions:
    - mkdocs-click

添加CLI应用程序，例如

# 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."""

在Markdown中添加mkdocs-click块

# CLI Reference

This page provides documentation for our command line tools.

::: mkdocs-click
    :module: app.cli
    :command: cli

启动文档服务器

mkdocs serve

太好了！💫

用法

记录命令

要为命令添加文档，请将mkdocs-click块添加到文档应插入的位置。

示例

::: mkdocs-click
    :module: app.cli
    :command: main

有关所有可用选项，请参阅块语法。

多命令支持

当指向一组（或任何其他多命令）时，mkdocs-click还将生成子命令的文档。

这使得您可以通过将mkdocs-click指向根命令来生成整个CLI应用程序的文档。

调整标题级别

默认情况下，mkdocs-click为根命令部分生成从<h1>开始的Markdown标题。当文档应填充整个页面时，这通常是您想要的。

如果您在其他Markdown内容中插入文档，可以设置:depth:选项来调整初始标题级别。请注意，即使您只是添加一个标题，这也适用。

默认设置为0，即标题从<h1>开始。如果设置为1，则标题将从<h2>开始，依此类推。请注意，如果您插入自己的第一级标题并将深度保留在默认值0，则页面将具有多个<h1>标签，这不符合生成页面内部菜单的主题，如ReadTheDocs和mkdocs-material主题。

完整的命令路径标题

默认情况下，mkdocs-click输出包含命令名称的标题。对于嵌套命令（如$ cli build all），这也意味着标题将是## all。这可能令人惊讶，并且对于高度嵌套的CLI应用程序，在视觉上可能更难导航。

如果您想显示完整的命令路径，请启用属性列表扩展

# mkdocs.yaml

markdown_extensions:
    - attr_list
    - mkdocs-click

然后mkdocs-click将在标题（例如## cli build all）和永久链接（例如#cli-build-all）中输出完整的命令路径。

请注意，目录（TOC）仍将使用命令名称：目录自然是层次化的，因此完整的命令路径将是冗余的。（这是为什么需要attr_list扩展的原因。）

参考

块语法

mkdocs-click块的语法如下

::: mkdocs-click
    :module: <MODULE>
    :command: <COMMAND>
    :prog_name: <PROG_NAME>
    :depth: <DEPTH>
    :style: <STYLE>

选项

• module：命令对象所在模块的路径。
• command：命令对象的名称。
• prog_name：（可选，默认：与command相同）显示命令的名称。
• depth：（可选，默认：0）生成标题时添加的偏移量。
• style：（可选，默认：plain）选项部分的样式。可能的选项是plain和table。
• remove_ascii_art：（可选，默认：False）当文档字符串以转义字符\b开始时，所有文本都将被忽略，直到遇到下一个空白行。
• show_hidden：（可选，默认：False）显示标记为隐藏的命令和选项。
• list_subcommands：（可选，默认：False）列出给定命令的子命令。如果安装了attr_list，还将添加子命令的链接。