sphinx-contrib/typer

Auto generate docs for typer and click commands using typer's rich console formatting.

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:

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.

typer's Issues

nested class attribute import paths for typer apps are broken.

This effects commands defined using django-typer.

Should be able to import like so:

django_typer.management.commands.shellcompletion.Command::typer_app

When using convert-png sometimes the pngs images are cutoff too short.

When the sphinx app is an attribute on a class the import fails.

Move to ruff for tooling

Convert README and CONTRIBUTING to markdown.

Sick of lackluster rst support...

https://github.com/orgs/community/discussions/113792

typer 0.12.0 package split breaks upgrades.

Issue explained here:

bckohan/django-typer#47

Should issue a new release dependent on typer-slim instead of typer.

when :prog: is supplied and a subcommand help is generated the usage string includes incorrect prefix to prog

Typer dependency erroneously downgraded.

^0.6.1 slipped in.

Typer with `sphinx-autobuild` going on infinite loop

Hi, I just started using typer on my project documentation and it's great!

During my development, I use sphinx-autobuild plugin to automatically re-render the documentation when I modify anything in the /docs folder, including the conf.py file.

When I run sphinx-autobuild the docs get built and rendered correctly. However, at the end of it, it says conf.py was modified and the modification was typer_render_html.

I noticed this is the configuration for sphinx-contrib/typer, however, I am just using the defaults. Is the typer extension for sphinx modifying the conf.py file to add its default parameters?

I think this is a bug, or if I am doing something wrong please let me know.

I tried adding the configuration manually to conf.py with default values, which works, but I don't want to specify all the defaults in the conf.py file :) NVM, I was wrong, it still has the same infinite loop.

Thanks!

typer-slim[all] no longer works to bring in rich

The dependency should be typer-slim[standard] to also install rich.

Proxied Typer object check is broken.

The duck typing check released with 0.2.4 does not actually work.

Some dependencies have unnecessarily recent version requirements.

Add entry point to docs

Hi @bckohan,

thank you for the very useful contribution to sphinx for parsing the typer documentation!

I'm managing to use it properly, but in my package I defined the CLI options in the __main__.py file and simply defined an entrypoint in my setup.py script.

entry_points={
        "console_scripts": ["toolname=toolname.__main__:main"],
    },

When building the documentation with sphinx I get though the __main__ string as the command and not the set up entry point.

Is there a way to configure the parsing for the documentation so that it considers this entrypoint?

Fix WARNING: cannot cache unpickable configuration value

WARNING: cannot cache unpickable configuration value: 'typer_get_iframe_height' (because it contains a function, class, or module object)

The configuration is pickled and versions of Sphinx > 7.3 are complaining. Should probably move these functions to import paths.

Support more flexible duck typing for detecting Typer objects

For instance django-typer proxies typer objects to bind them to command instances. But this means they don't pass isinstance(obj, Typer) checks - use a duck typing check for an info object to allow getattr style proxy objects for maximum compatibility.

Pillow version not specified for png optional dependency.

This was introduced in the 0.1.9 release.