manpages builder uses bold for entire options

[CendioOssman]

Describe the bug

Unfortunately the manpages writer doesn't follow the conventions of man pages when it generates the output for .. option:: directives. It makes the entire line bold, not just the literal parts.

How to Reproduce

Run this through the manpages builder:

.. option:: -p PROJECT, --project=PROJECT
   Project name will be set.

You'll get:

.B \-p PROJECT, \-\-project=PROJECT
Project name will be set.

Expected behavior

\fB\-p\fR \fIPROJECT\fR, \fB\-\-project\fR=\fIPROJECT\fR
Project name will be set.

Your project

N/A

Screenshots

No response

OS

Linux

Python version

3.6.12

Sphinx version

4.2.0

Sphinx extensions

No response

Extra tools

No response

Additional context

No response

[CendioOssman]

It looks like this problem has two parts to it:

1. The manpage writer handles the entire signature as a "term", ignoring any internal markup
2. The option directive unfortunately doesn't parse things in much detail. The option itself becomes a desc_name, and everything else becomes desc_addname. It doesn't separate punctuation from identifiers.

[CendioOssman]

I'm guessing the second point is resolved by #10366? @marxin?

[tk0miya]

This is generated doctree (w/ HEAD of 5.x branch)

        <desc classes="std option" desctype="option" domain="std" noindex="False" objtype="option">
            <desc_signature allnames="-p --project" classes="sig sig-object std sig sig-object" ids="cmdoption-p cmdoption-project">
                <desc_name classes="sig-name descname sig-name descname" xml:space="preserve">
                    -p
                <desc_addname classes="sig-prename descclassname sig-prename descclassname" xml:space="preserve">
                     PROJECT
                <desc_addname classes="sig-prename descclassname sig-prename descclassname" xml:space="preserve">
                    ,
                <desc_name classes="sig-name descname sig-name descname" xml:space="preserve">
                    --project
                <desc_addname classes="sig-prename descclassname sig-prename descclassname" xml:space="preserve">
                    =PROJECT
            <desc_content>
                <paragraph>
                    Project name will be set.

As you said, the option value is now parsed as a desc_addname node. But it's not good to render it as an italic text because desc_addname is also used for other purposes. For example, this is a doctree of py:class definition. In this case, it's used for the module name.

        <desc classes="py class" desctype="class" domain="py" noindex="False" objtype="class">
            <desc_signature class="" classes="sig sig-object py sig sig-object" fullname="Dummy" ids="example.Dummy" module="example">
                <desc_annotation xml:space="preserve">
                    class
                    <desc_sig_space classes="w w">

                <desc_addname classes="sig-prename descclassname sig-prename descclassname" xml:space="preserve">
                    example.
                <desc_name classes="sig-name descname sig-name descname" xml:space="preserve">
                    Dummy
                <desc_parameterlist xml:space="preserve">
                    <desc_parameter xml:space="preserve">
                        <desc_sig_name classes="n n">
                            arg

[CendioOssman]

That looks like the same output as 4.2.0 is giving me. Was the new syntax from #10366 used in your test?

[marxin]

I see the following when using option_emphasise_placeholders = True:

where the first one is using it and the second one not:

.. option:: -foo={BAR}, -f {BAR} {BAZ}

  Using emphasising placeholders.

.. option:: -foo=BAR, -f BAR BAZ

   Normal option values.

[CendioOssman]

Nice. Looks like the biggest issue is resolved then.

The = and , shouldn't be bold, but that's a minor issue compared to the placeholders.