Grouping Sphinx object definition directives

[Nineteendo (Nice Zombies)]

If you repeat Sphinx directives they are separated by an empty line. For example:

python/cpython/blob/f70395786f6da2412d7406606feb64347fc71262/Doc/library/typing.rst?plain=1#L1974-L1975

Renders with a newline:

Could be changed to, which is more readable:

.. data:: ParamSpecArgs
          ParamSpecKwargs

And renders without a newline:

Regexes:

• \.\. attribute::.*\n \.\. attribute::: 35 matches
• \.\. data::.*\n \.\. data::: 2 matches
• \.\. decorator::.*\n \.\. decorator::: 1 match
• \.\. index::.*\n \.\. index::: 3 matches
• \.\. method::.*\n \.\. method::: 3 matches
• \.\. versionadded::.*\n \.\. versionadded::: 1 match
• \.\. versionchanged::.*\n \.\. versionchanged::: 1 match
• \.\. attribute::.*\n\.\. attribute::: 4 matches
• \.\. data::.*\n\.\. data::: 6 matches
• \.\. describe::.*\n\.\. describe::: 1 match
• \.\. exception::.*\n\.\. exception::: 1 match
• \.\. function::.*\n\.\. function::: 11 matches
• \.\. index::.*\n\.\. index::: 2 matches
• \.\. method::.*\n\.\. method::: 2 matches
• \.\. module::.*\n\.\. module::: 1 match
• \.\. moduleauthor::.*\n\.\. moduleauthor::: 13 matches
• \.\. opcode::.*\n\.\. opcode::: 1 match
• \.\. option::.*\n\.\. option::: 17 matches
• \.\. sectionauthor::.*\n\.\. sectionauthor::: 26 matches
• \.\. versionadded::.*\n\.\. versionadded::: 4 matches

What’s your opinion?

• Group
• Don’t group

[AA-Turner (Adam Turner)]

I think I understand your point, but the argument is fairly unclear here — especially regarding the tradeoffs w.r.t. churn.

Is there a middle ground, rather than simply arguing to change everything?

A

[Nineteendo (Nice Zombies)]

I would like to discuss which cases we want to change (maybe with abstract examples).
If a decision is made, I’ll update the files accordingly.

My main issue is that the description for the first definitions seems to be missing because of the empty line.

[steve.dower]

Yeah, churn counts against this, but it’s something I didn’t know about and I much prefer the tighter grouping visually.

Do we have a coding/style guide for the docs? This is probably in the category of “do it when we touch nearby docs, but don’t do it just for the sake of it”.

[hugovk (Hugo van Kemenade)]

There’s some earlier discussion at:

Don't needlessly repeat Sphinx directives

Where I concluded:

But I also couldn’t find any specific accessibility advice either way for this, and I’m not sure how much of a problem this is solving, and there’s probably more important things we can work on, so we might not want to do a full docs sweep?

[nedbat (Ned Batchelder)]

@steve.dower

Do we have a coding/style guide for the docs? This is probably in the category of “do it when we touch nearby docs, but don’t do it just for the sake of it”.

There is a style guide, both for Sphinx details (devguide: reStructuredText markup) and English usage (the devguide section before that one).

[Nineteendo (Nice Zombies)]

It does give an example of this, but doesn’t mention the grouping explicitly:

.. function:: spam(eggs)
              ham(eggs)
   :noindex:

   Spam or ham the foo.

It also uses the other style (reStructuredText markup):

:mod:`parrot` -- Dead parrot access
===================================

.. module:: parrot
   :platform: Unix, Windows
   :synopsis: Analyze and reanimate dead parrots.
.. moduleauthor:: Eric Cleese <eric@python.invalid>
.. moduleauthor:: John Idle <john@python.invalid>

[Nineteendo (Nice Zombies)]

@hugovk where do we best add accessibility advice?

[encukou (Petr Viktorin)]

For ReST tooling (e.g. showing ParamSpecArgs docs for an IDE tooltip), grouped is better: the following paragraphs are attached to all of the definitions. Ungrouped means there’s, semantically, an extra entry with just a signature.

This shows up in the HTML structure too. I don’t know what the effect on screen readers is, but proper structure can’t hurt :‍)