Auto generate docs for typer commands.
Project description
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: htmlThis would generate html that looks like this:
You could change :preferred: to svg, to generate svg instead:
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.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file sphinxcontrib_typer-0.1.0.tar.gz.
File metadata
- Download URL: sphinxcontrib_typer-0.1.0.tar.gz
- Upload date:
- Size: 14.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.7.1 CPython/3.11.4 Darwin/23.1.0
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 8d6b7c1f08fc6a0e6672a0343fd29bde4e49eb04df86419a32f1a37fea6c604d |
|
| MD5 | 398404c6eb92e3fea5f36ef298c6dd25 |
|
| BLAKE2b-256 | 23fbf5267d657f32ccc5d9998d1121cf356d8732cfc0efbec45eead01a70f113 |
File details
Details for the file sphinxcontrib_typer-0.1.0-py3-none-any.whl.
File metadata
- Download URL: sphinxcontrib_typer-0.1.0-py3-none-any.whl
- Upload date:
- Size: 12.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.7.1 CPython/3.11.4 Darwin/23.1.0
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 122cfa78bff246457bc05fe68895156f7d0620d0177a4df49f8ffb802a465323 |
|
| MD5 | 336ca572de184b07b9b1cba11b267702 |
|
| BLAKE2b-256 | ffabb079f67f1498790f2b665a28bd5aa5427ce551f1a38746e3f28337a711e9 |
