search

click-contrib / sphinx-click

A Sphinx plugin to automatically document click-based applications
MIT License
212 stars 57 forks source link

Documentation of arguments #143

Closed mtribiere closed 3 weeks ago

mtribiere commented 3 weeks ago

https://github.com/click-contrib/sphinx-click/blob/7f29172b10d4dc251af414ae01e38c3b970686a1/sphinx_click/ext.py#L222

If I understand correctly, arguments in Click cannot have a help field. If so, how is possible to document such arguments instead of just having Require argument.

Would an approach similar to autodoc be possible?

def do_this(parameter1: int, parameter2: MyClass):
   """
   This function does this.

   :param parameter1: my favorite int
   :param parameter2: my favorite class
   """
   return parameter1 + parameter2.i
stephenfin commented 3 weeks ago

That exists because of https://github.com/click-contrib/sphinx-click/pull/134. As that PR noted, you can't set help text for Arguments in Click but you can subclass that and create your own argument types. I'd encourage you to do the same if necessary. I don't see us adding additional parsing of docstrings here.