sphinx
sphinx copied to clipboard
extend option directive syntax
The motivation of pull request is a documentation syntax we use in GCC docs (working on the porting):
.. option:: -Wimplicit-fallthrough
:option:`-Wimplicit-fallthrough` is the same as :option:`-Wimplicit-fallthrough=3`
and :option:`-Wno-implicit-fallthrough` is the same as
:option:`-Wimplicit-fallthrough=0`.
.. option:: -Wno-implicit-fallthrough
Default setting; overrides :option:`-Wimplicit-fallthrough`.
.. option:: -Wimplicit-fallthrough#{n}
Warn when a switch case falls through. For example:
...
.. option:: -Wimplicit-fallthrough#0
Disable it altogether.
.. option:: -Wimplicit-fallthrough#1
Level 1
.. option:: -Wimplicit-fallthrough#2
Level 2
.. option:: -Wimplicit-fallthrough#3
Level 3
...
Try :option:`-Wimplicit-fallthrough=` or :option:`-Wimplicit-fallthrough` or :option:`-Wimplicit-fallthrough=n`
As seen, we basically need to distinguish:
-Woptionand-Woption=directives-Woption=value1,-Woption=value2, ...
Where it would be handy to reference to any of the aforementioned versions. I came up with a new syntax # that is a non-breaking version of =. Is the suggestion something the community would accept?
Example: https://splichal.eu/tmp/demo2/html/