sphinx-doc / sphinx-doc/sphinx
Request for a command synopsis directive
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
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*>
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
The request targets a new cmdsynopsis directive modeled on option::; start by tracing the existing option:: directive. Use the provided reStructuredText examples to define the synopsis form and verify that option dashes and emphasis render without smartypants corruption.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100