sphinx icon indicating copy to clipboard operation
sphinx copied to clipboard

extend option directive syntax

Open marxin opened this issue 3 years ago • 0 comments

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:

  1. -Woption and -Woption= directives
  2. -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/

marxin avatar Sep 20 '22 10:09 marxin