search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.63k stars 2.13k forks source link

Request for a command synopsis directive #9784

Open CendioOssman opened 3 years ago

CendioOssman commented 3 years ago

Is your feature request related to a problem? Please describe.

I'd like to get correct format of a command synopsis line without having to deal with all the details manually. Right now there is the option:: directive that deals with explaining the options and highlighting those correctly. But you have to manually tag up the synopsis section of e.g. a man page.

As an example of an annoying detail is that smartypants messes up your --.

Describe the solution you'd like

I'd like to be able to specify:

Synopsis
--------

.. cmdsynopsis:: my-command -o <output> [--verbose|--quiet] [options] <input>

Describe alternatives you've considered

Right now you have to manually tag things, e.g.:

Synopsis
--------

my-command **-o** <*output*> [**\-\-verbose**|**\-\-quiet**] [*options*] <*input*>
CendioOssman commented 3 years ago

As for the format, this is probably a start:

https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html