search

click-contrib / sphinx-click

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

ENH allow to exclude some sub-commands automatically #72

Closed tomMoral closed 3 years ago

tomMoral commented 3 years ago

First of all, thanks for this very nice package! It makes the documentation of click based application very easy.

We are developing a command line tool and we have some private sub-commands that we would like to exclude from the doc. I know that I can select the subcommands that are documented using the :commands: directive.

However, most sub-commands need to be included in our case so having a easy way to exclude "private" commands would be very nice, either having a :exclude: directive or not documenting certain patterns, for instances sub-commands starting with _. WDYT?

stephenfin commented 3 years ago

Would it be possible to use hidden commands? If these commands are truly private you probably want to hide them in the CLI docs (i.e. --help) too.

If not, this does sound reasonable and could probably be achieved by replacing the :commands: option with :include: and :exclude: options. I can't promise I'll get to this in the next while but I'd be happy to review a PR if anyone could work on it.

tomMoral commented 3 years ago

You are right, hidden is what I need and it works well with sphinx-click as the command is not displayed. Thanks!

Not sure if the :exclude: is really useful as my aim was mainly for private sub-commands and :hidden: is better as it also makes it private in for the CLI help. If you think it is not useful, feel free to close this issue. Else, I might give it a try if I get some spare time :).

stephenfin commented 3 years ago

Yeah, given private exists there's probably no immediate need for this