Skip to main content

Auto generate docs for typer commands.

Project description

MIT license PyPI version fury.io PyPI pyversions PyPI status Documentation Status Code Cov Test Status

sphinxcontrib-typer

A Sphinx directive for auto generating docs for Typer (and Click commands!) using the rich console formatting available in Typer. This package generates concise command documentation in text, html or svg formats out of the box, but if your goal is to greatly customize the generated documentation sphinx-click may be more appropriate and will also work for Typer commands.

Installation

Install with pip:

pip install sphinxcontrib-typer

Add sphinxcontrib.typer to your conf.py file:

# be sure that the commands you want to document are importable
# from the python path when building the docs
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent / '../path/to/your/commands'))

extensions = [
    ...
    'sphinxcontrib.typer',
    ...
]

Usage

Say you have a command in the file examples/example.py that looks like this:

import typer
import typing as t

app = typer.Typer(add_completion=False)

@app.callback()
def callback(
    flag1: bool = typer.Option(False, help="Flag 1."),
    flag2: bool = typer.Option(False, help="Flag 2.")
):
    """This is the callback function."""
    pass


@app.command()
def foo(
    name: str = typer.Option(..., help="The name of the item to foo.")
):
    """This is the foo command."""
    pass


@app.command()
def bar(
    names: t.List[str] = typer.Option(..., help="The names of the items to bar."),
):
    """This is the bar command."""
    pass


if __name__ == "__main__":
    app()

You can generate documentation for this command using the typer directive like so:

.. typer:: examples.example.app
    :prog: example1
    :width: 70
    :preferred: html

This would generate html that looks like this:

https://raw.githubusercontent.com/sphinx-contrib/typer/main/example.html.png

You could change :preferred: to svg, to generate svg instead:

https://raw.githubusercontent.com/sphinx-contrib/typer/main/example.svg

Or to text:

Usage: example [OPTIONS] COMMAND [ARGS]...

This is the callback function.

╭─ Options ──────────────────────────────────────────────────────────╮
│ --flag1    --no-flag1      Flag 1. [default: no-flag1]             │
│ --flag2    --no-flag2      Flag 2. [default: no-flag2]             │
│ --help                     Show this message and exit.             │
╰────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────╮
│ bar           This is the bar command.                             │
│ foo           This is the foo command.                             │
╰────────────────────────────────────────────────────────────────────╯

The typer directive has options for generating docs for all subcommands as well and optionally generating independent sections for each. There are also mechanisms for passing options to the underlying console and svg generation functions. See the official documentation for more information.

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

sphinxcontrib_typer-0.1.10.tar.gz (14.7 kB view details)

Uploaded Source

Built Distribution

sphinxcontrib_typer-0.1.10-py3-none-any.whl (13.2 kB view details)

Uploaded Python 3

File details

Details for the file sphinxcontrib_typer-0.1.10.tar.gz.

File metadata

  • Download URL: sphinxcontrib_typer-0.1.10.tar.gz
  • Upload date:
  • Size: 14.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.7.1 CPython/3.11.4 Darwin/23.2.0

File hashes

Hashes for sphinxcontrib_typer-0.1.10.tar.gz
Algorithm Hash digest
SHA256 3e42029ea9714f4600970ce5ad8294b7b58f2d8c7c81327094a37954e4f5b10a
MD5 a66c19b25cd4806fc63782f3abaaf1eb
BLAKE2b-256 a686503fb94d2edd4dde1e520d181c6def4e20caac99cd25fbb73399b4888821

See more details on using hashes here.

File details

Details for the file sphinxcontrib_typer-0.1.10-py3-none-any.whl.

File metadata

File hashes

Hashes for sphinxcontrib_typer-0.1.10-py3-none-any.whl
Algorithm Hash digest
SHA256 368e3edc8f509bfeabf7c17bcc2a38323dc25407fac6c3d63a4ff99c413a388e
MD5 4eb16f589dae4c7b7cf78d1e5032e4c7
BLAKE2b-256 717159a98104d3d1176e0b263253fe6a5d855cf2c79893e906f3eeb29c8e7c06

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