extend option directive syntax

[marxin]

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]

A bit of context: as you likely know I'm working on transition of th GCC compiler documentation from Texinfo to Sphinx and this feature would help you reference option much better. As seen, we commonly document option values.

Is the Sphinx community interested in the feature? I can add more tests and document it.
What do you think @AA-Turner, @tk0miya ?

[AA-Turner]

My concern is about making the option directive too complicated to maintain for quite a niche usecase.

Is it possible in your conversion work to implement a custom option directive that works for GCC, or a flag to the standard option directive that hooks into your extra processing? If there are constraints that GCC must use only vanilla Sphinx then those routes aren't useable, clearly.

Is the following style usable?

.. option:: -Wimplicit-fallthrough

   Warn when a switch case falls through. Legal values are:
  
   - 0: Disable it altogether.
   - 1: Level 1
   - 2: Level 2
   - 3: Level 3

   :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`.

Try :option:`-Wimplicit-fallthrough=` or :option:`-Wimplicit-fallthrough` or :option:`-Wimplicit-fallthrough=n`

This would only require changing the option role to ignore = and anything after =.

A

[marxin]

My concern is about making the option directive too complicated to maintain for quite a niche usecase.

I do share the concert about the maintainability of the functionality.

Is it possible in your conversion work to implement a custom option directive that works for GCC, or a flag to the standard option directive that hooks into your extra processing? If there are constraints that GCC must use only vanilla Sphinx then those routes aren't useable, clearly.

We would like to support only vanilla Sphinx.

Is the following style usable?

.. option:: -Wimplicit-fallthrough

   Warn when a switch case falls through. Legal values are:
  
   - 0: Disable it altogether.
   - 1: Level 1
   - 2: Level 2
   - 3: Level 3

   :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`.

Try :option:`-Wimplicit-fallthrough=` or :option:`-Wimplicit-fallthrough` or :option:`-Wimplicit-fallthrough=n`

Yes, that's a feasible solution for us, I think.

This would only require changing the option role to ignore = and anything after =.

Yep. That would be a pretty small change, let me push it.

[AA-Turner]

Please merge 5.x to fix mypy

[AA-Turner]

Please also add a CHANGES entry

[marxin]

Both done now.

[AA-Turner]

I don't like the GitHub UI where you're not prompted to review the commit message if your last merge was a "rebase and merge"... for posterity I was going to use:

Allow cross referencing options with values (#10840)

This change means that text following `=` is ignored when searching for a
corresponding option directive to an option cross reference role.

A

[marxin]

I like the wording improvement, please commit it.