search

click-contrib / sphinx-click

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

How can I document only the sub-command without showing the doc from the group? #53

Closed williamjamir closed 4 years ago

williamjamir commented 4 years ago

I want to create an entry for each sub-command:

.. click:: my_project.cli:main
    :prog: my-project
    :show-nested:
    :commands: template

Some text in my documentation 

.. click:: my_project.cli:main
    :prog: my-project
    :show-nested:
    :commands: package

But the "problem" is that the docstring from the command main is written twice.

my-project
[docstring from main]

my-project [OPTIONS] COMMAND [ARGS]...

template
[docstring of template command]

my-project template [OPTIONS]

Options
[options from template]

Some text from my documentation 

my-project
[docstring from main]

my-project [OPTIONS] COMMAND [ARGS]...

package
[docstring of package command]

my-project package [OPTIONS]

Options
[options from package]

Do you know some way to avoid this "duplication"? I mean how can I hide the sections

my-project
[docstring from main]

my-project [OPTIONS] COMMAND [ARGS]...

It's possible?

stephenfin commented 4 years ago

Assuming your code is all in one module, instead of:

.. click:: my_project.cli:main
    :prog: my-project
    :show-nested:
    :commands: template

Try:

.. click:: my_project.cli:template
    :prog: my-project template
    :show-nested:

If it's separate modules, just point to those, e.g.:

.. click:: my_project.template:main
    :prog: my-project template
    :show-nested:
stephenfin commented 4 years ago

If you were able to submit a patch to indicate this in the documentation, I'd appreciate it. It's obviously not as clear as it could be :smile: