Metadata-Version: 2.1
Name: mkdocs-click
Version: 0.2.0
Summary: An MkDocs extension to generate documentation for Click command line applications
Home-page: https://github.com/DataDog/mkdocs-click
Author: Datadog
Author-email: packages@datadoghq.com
License: Apache
Description: # mkdocs-click
        
        ![Tests](https://github.com/DataDog/mkdocs-click/workflows/Tests/badge.svg?branch=master)
        ![Python versions](https://img.shields.io/pypi/pyversions/mkdocs-click.svg)
        [![Package version](https://badge.fury.io/py/mkdocs-click.svg)](https://pypi.org/project/mkdocs-click)
        
        An MkDocs extension to generate documentation for Click command line applications.
        
        ## 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! 💫
        
        ![](https://raw.githubusercontent.com/DataDog/mkdocs-click/master/docs/example.png)
        
        ## 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.
        
        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:
        
        ```markdown
        ::: mkdocs-click
            :module: <MODULE>
            :command: <COMMAND>
            :prog_name: <PROG_NAME>
            :depth: <DEPTH>
        ```
        
        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.
        
        
        # Changelog
        
        All notable changes to this project will be documented in this file.
        
        The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
        
        ## 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.
        
Keywords: mkdocs datadog click
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Python: >=3.7
Description-Content-Type: text/markdown
