| Name | mkdocs-click JSON |
| Version |
0.8.1
JSON |
| download |
| home_page | |
| Summary | An MkDocs extension to generate documentation for Click command line applications |
| upload_time | 2023-09-18 18:36:09 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.7 |
| license | |
| keywords |
click
datadog
mkdocs
mkdocs-plugin
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# mkdocs-click
[](https://pypi.org/project/mkdocs-click/)
An MkDocs extension to generate documentation for Click command line applications.
Originally developed by [Datadog](https://www.datadoghq.com).
## Installation
Install from PyPI:
```bash
pip install mkdocs-click
```
## Quickstart
Add `mkdocs-click` to Markdown extensions in your `mkdocs.yml` configuration:
```yaml
site_name: Example
theme: readthedocs
markdown_extensions:
- mkdocs-click
```
Add a CLI application, e.g.:
```python
# 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:
```markdown
# CLI Reference
This page provides documentation for our command line tools.
::: mkdocs-click
:module: app.cli
:command: cli
```
Start the docs server:
```bash
mkdocs serve
```
Tada! 💫
## Usage
### Documenting commands
To add documentation for a command, add a `mkdocs-click` block where the documentation should be inserted.
Example:
```markdown
::: mkdocs-click
:module: app.cli
:command: main
```
For all available options, see the [Block syntax](#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](https://python-markdown.github.io/extensions/attr_list/):
```yaml
# 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:
```markdown
::: 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.
- `show_hidden`: _(Optional, default: `False`)_ Show commands and options that are marked as hidden.
- `list_subcommands`: _(Optional, default: `False`)_ List subcommands of a given command. If _attr_list_ is installed,
add links to subcommands also.
Raw data
{
"_id": null,
"home_page": "",
"name": "mkdocs-click",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "click,datadog,mkdocs,mkdocs-plugin",
"author": "",
"author_email": "Datadog <packages@datadoghq.com>",
"download_url": "https://files.pythonhosted.org/packages/68/61/d6b68573b4c399cd201502e4ea4cbfc12e274333d9ee622668cfbc9940ac/mkdocs_click-0.8.1.tar.gz",
"platform": null,
"description": "# mkdocs-click\n\n\n\n[](https://pypi.org/project/mkdocs-click/)\n\nAn MkDocs extension to generate documentation for Click command line applications.\n\nOriginally developed by [Datadog](https://www.datadoghq.com).\n\n## Installation\n\nInstall from PyPI:\n\n```bash\npip install mkdocs-click\n```\n\n## Quickstart\n\nAdd `mkdocs-click` to Markdown extensions in your `mkdocs.yml` configuration:\n\n```yaml\nsite_name: Example\ntheme: readthedocs\n\nmarkdown_extensions:\n - mkdocs-click\n```\n\nAdd a CLI application, e.g.:\n\n```python\n# app/cli.py\nimport click\n\n@click.group()\ndef cli():\n \"\"\"Main entrypoint.\"\"\"\n\n@cli.command()\n@click.option(\"-d\", \"--debug\", help=\"Include debug output.\")\ndef build(debug):\n \"\"\"Build production assets.\"\"\"\n```\n\nAdd a `mkdocs-click` block in your Markdown:\n\n```markdown\n# CLI Reference\n\nThis page provides documentation for our command line tools.\n\n::: mkdocs-click\n :module: app.cli\n :command: cli\n```\n\nStart the docs server:\n\n```bash\nmkdocs serve\n```\n\nTada! \ud83d\udcab\n\n\n\n## Usage\n\n### Documenting commands\n\nTo add documentation for a command, add a `mkdocs-click` block where the documentation should be inserted.\n\nExample:\n\n```markdown\n::: mkdocs-click\n :module: app.cli\n :command: main\n```\n\nFor all available options, see the [Block syntax](#block-syntax).\n\n### Multi-command support\n\nWhen pointed at a group (or any other multi-command), `mkdocs-click` will also generate documentation for sub-commands.\n\nThis allows you to generate documentation for an entire CLI application by pointing `mkdocs-click` at the root command.\n\n### Tweaking header levels\n\nBy 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.\n\nIf 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.\n\nBy 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.\n\n### Full command path headers\n\nBy 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.\n\nIf you'd like to show the full command path instead, turn on the [Attribute Lists extension](https://python-markdown.github.io/extensions/attr_list/):\n\n```yaml\n# mkdocs.yaml\n\nmarkdown_extensions:\n - attr_list\n - mkdocs-click\n```\n\n`mkdocs-click` will then output the full command path in headers (e.g. `## cli build all`) and permalinks (e.g. `#cli-build-all`).\n\nNote 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.)\n\n## Reference\n\n### Block syntax\n\nThe syntax for `mkdocs-click` blocks is the following:\n\n```markdown\n::: mkdocs-click\n :module: <MODULE>\n :command: <COMMAND>\n :prog_name: <PROG_NAME>\n :depth: <DEPTH>\n :style: <STYLE>\n```\n\nOptions:\n\n- `module`: Path to the module where the command object is located.\n- `command`: Name of the command object.\n- `prog_name`: _(Optional, default: same as `command`)_ The name to display for the command.\n- `depth`: _(Optional, default: `0`)_ Offset to add when generating headers.\n- `style`: _(Optional, default: `plain`)_ Style for the options section. The possible choices are `plain` and `table`.\n- `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.\n- `show_hidden`: _(Optional, default: `False`)_ Show commands and options that are marked as hidden.\n- `list_subcommands`: _(Optional, default: `False`)_ List subcommands of a given command. If _attr_list_ is installed,\nadd links to subcommands also.\n",
"bugtrack_url": null,
"license": "",
"summary": "An MkDocs extension to generate documentation for Click command line applications",
"version": "0.8.1",
"project_urls": {
"Changelog": "https://github.com/mkdocs/mkdocs-click/blob/master/CHANGELOG.md",
"Issues": "https://github.com/mkdocs/mkdocs-click/issues",
"Source": "https://github.com/mkdocs/mkdocs-click"
},
"split_keywords": [
"click",
"datadog",
"mkdocs",
"mkdocs-plugin"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8ece12158add31617ea579f7975f502812555371d7b8a4410c993a27d7e20727",
"md5": "edbaaea667221dfe8ed0402bc557f855",
"sha256": "a100ff938be63911f86465a1c21d29a669a7c51932b700fdb3daa90d13b61ee4"
},
"downloads": -1,
"filename": "mkdocs_click-0.8.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "edbaaea667221dfe8ed0402bc557f855",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 14862,
"upload_time": "2023-09-18T18:36:08",
"upload_time_iso_8601": "2023-09-18T18:36:08.172975Z",
"url": "https://files.pythonhosted.org/packages/8e/ce/12158add31617ea579f7975f502812555371d7b8a4410c993a27d7e20727/mkdocs_click-0.8.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6861d6b68573b4c399cd201502e4ea4cbfc12e274333d9ee622668cfbc9940ac",
"md5": "4097c097e7d178100d3b51e36c6ceed1",
"sha256": "0a88cce04870c5d70ff63138e2418219c3c4119cc928a59c66b76eb5214edba6"
},
"downloads": -1,
"filename": "mkdocs_click-0.8.1.tar.gz",
"has_sig": false,
"md5_digest": "4097c097e7d178100d3b51e36c6ceed1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 17874,
"upload_time": "2023-09-18T18:36:09",
"upload_time_iso_8601": "2023-09-18T18:36:09.887484Z",
"url": "https://files.pythonhosted.org/packages/68/61/d6b68573b4c399cd201502e4ea4cbfc12e274333d9ee622668cfbc9940ac/mkdocs_click-0.8.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-18 18:36:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mkdocs",
"github_project": "mkdocs-click",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-click"
}
