[QUESTION] Typer CLI in sphinx

[OskarLiew]

First check

• [x] I used the GitHub search to find a similar issue and didn't find it.
• [x] I searched the Typer documentation, with the integrated search.
• [x] I already searched in Google "How to X in Typer" and didn't find any information.
• [x] I already searched in Google "How to X in Click" and didn't find any information.

Description

I have written a typer CLI and I have created automated documentation for it using sphinx and autodoc. But I have encountered an issue where the documentation reads:

cli.assign(name: str = <typer.models.ArgumentInfo object>, version: str = <typer.models.ArgumentInfo object>)

where I would like it to say:

cli.assign(name: str, version: str).

Is it possible to expose the standard value to autodoc? I found a potential fix in https://stackoverflow.com/questions/12082570/override-function-declaration-in-autodoc-for-sphinx/12087750#12087750 where you can use the first row of the docstring to change the documented signature. This unfortunately changes the assign --help output. Is it possible to hide a single row from --help?

[xeor]

Did you get further on your quest? Do you mind share how you are doing autodoc? Looking for the same

[OskarLiew]

The rst for the autodocs page is

.. _cli-reference:

Command-line Interface
======================

.. automodule:: mvi.cli.cli
   :members:
   :undoc-members:
   :show-inheritance:

and the following extensions in conf.py:

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
    "sphinx_rtd_theme",
    "sphinx.ext.doctest",
    "sphinx_multiversion",
]

The result ends up looking like this: https://vikinganalytics.github.io/mvi-docs/0.4.3/content/api_reference/cli.html

I also found this answer on stack overflow about how to change the signature in the rst, but it has to be updated everytime we make a change in the signature of a CLI command, so we opted to not do it: https://stackoverflow.com/questions/5365684/is-it-possible-to-override-sphinx-autodoc-for-specific-functions/5368194#5368194

It might be possible to write a custom extension for sphinx that can handle typer function signatures a bit nicer, but it is not something that we have prioritized.

[xeor]

Thanks for this! Very nice for api-doc (which I'm also going to do). I'm fairly new to sphinx, and this looks like a great module!

I'm not sure yet, but I think i'm ending up with just using click for the cli part for now because it seams like there really isnt a good way to autodocument this yet..

[edthamm]

I know it is not autodoc but it might help people in a similar spot that do not have a hard requirement on that. I actually like the documentation provided by sphinx_click.

Since typer uses click under the hood, you can use this by exposing the typer_click_object as input for that. How to get that is described here and using it works like this

.. click:: path.to.module:typer_click_object
   :prog: prog_name
   :nested: full

Hope someone finds this helpful.

[xeor]

That is awesome @edthamm ! If that works, it completely solves my problem! Thanks for sharing

[edthamm]

@xeor it works well enough for me. My use case is pretty light weight so it might well be that there are some things that do not work. Just saying YMMV. Anyways, happy to help.

One caveat I noticed for example is that the help text of arguments is not displayed in line with the arguments. Options work perfectly fine though. That is not a big deal for me as I do not use arguments often or at all in my application. And in case I do I document them in the doc-string as well. No big burden for me but maybe unbearable if you have to do loads of that.

[znichollscr]

Is it worth putting this comment in the docs? If so, I'd be happy to make a PR (but then I also think the credit would go at least slightly in the wrong place!)

https://github.com/tiangolo/typer/issues/200#issuecomment-795873331