Grouping Sphinx object definition directives

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

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
0 voters

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

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.

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”.

3 Likes

There’s some earlier discussion at:

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?

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

2 Likes

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>

@hugovk where do we best add accessibility advice?