Add optionlisting directive

[marxin]

Please support a new optionlisting directive:

..optionlisting:

  :option:`-fdiagnostics-plain-output`
  :option:`-fdiagnostics-show-location`:samp:`=[once|every-line]`
  :option:`-fdiagnostics-color`:samp:`=[auto|never|always]`

That would emit |gol| at the end of each line? Instead of manually placing the |gol| at the end of every line.

Originally reported in #9925.

[jakobandersen]

Do you mean this for declare multiple options a la the normal option directive (.. option::) but with a common description?
You can already now do

.. option:: -fdiagnostics-plain-output
            -fdiagnostics-show-location=[once|every-line]
            -fdiagnostics-color=[auto|never|always]

   Diagnostics options.

[marxin]

Do you mean this for declare multiple options a la the normal option directive (.. option::) but with a common description?

No, it's about using option role for a listing of already defined options. Something like:

Enable with -O2 optimization level:

..optionlisting:

  :option:`-fdiagnostics-plain-output`
  :option:`-fdiagnostics-show-location`:samp:`=[once|every-line]`
  :option:`-fdiagnostics-color`:samp:`=[auto|never|always]`

[jakobandersen]

Would it be possible to use a normal list?

[marxin]

Well, I don't want to emit the bullet points at the beginning of a line.

[jakobandersen]

Right. Then perhaps a line block might be useful:

| :option:`-fdiagnostics-plain-output`
| :option:`-fdiagnostics-show-location`:samp:`=[once|every-line]`
| :option:`-fdiagnostics-color`:samp:`=[auto|never|always]`

[marxin]

Kudos! It works perfectly well.

[marxin]

However, a small difference is the vertical spacing:

for

  Normal option3. Test :samp:`{samp}` and ``emph``.

  | :option:`-fdiagnostics-plain-output`
  | :option:`-fdiagnostics-show-location`:samp:`=[once|every-line]`
  | :option:`-fdiagnostics-color`:samp:`=[auto|never|always]`

Using GOL:

  :option:`-fdiagnostics-plain-output` |gol|
  :option:`-fdiagnostics-show-location`:samp:`=[once|every-line]` |gol|
  :option:`-fdiagnostics-color`:samp:`=[auto|never|always]` |gol|

rst_prolog = r'''
.. |gol| raw:: latex

               \\
'''