Don't needlessly repeat Sphinx directives

[nineteendo]

Documentation

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

cpython/Doc/library/typing.rst

Lines 1974 to 1975 in f703957

	.. data:: ParamSpecArgs
	.. data:: ParamSpecKwargs

Renders with a newline:

Could be changed to:

.. data:: ParamSpecArgs
          ParamSpecKwargs

Which 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

Linked PRs

• gh-118030: Group definitions for ParamSpecArgs and ParamSpecKwargs in typing.rst #118154
• [3.12] gh-118030: Group definitions for ParamSpecArgs and ParamSpecKwargs in typing.rst (GH-118154) #118155

[nineteendo]

@AlexWaygood, what should we do here?

[hugovk]

The original is better.

These are two method definitions, so a gap helps separate them when there's no description.

We can also consider accessibility and look at the HTML.

Here's the original: one <dl class="py method"> per method.

And the suggestion: only one <dl class="py method"> for both methods.

The original means we have consistent semantics, which is important for non-visual users with screen-readers or braille displays.

[AlexWaygood]

I agree with @hugovk -- if it's two different method definitions, or two different attribute definitions, then they should be separated by a newline.

Maybe some of the .. moduleauthor:: and .. section:: directives could be combined, but it's hard to say for certain without looking at specific instances.

[nineteendo]

These are two method definitions, so a gap helps separate them when there's no description.

Sorry, I should have clarified this: the description from the second method belongs to BOTH methods:

A number of Unix commands allow the user to intermix optional arguments with positional arguments. The parse_intermixed_args() and parse_known_intermixed_args() methods support this parsing style.

If there's a gap between, it looks like the description is missing (which is exactly what you thought), and it takes up vertical sceen space.

[hugovk]

Thanks for the clarification.

If there's a gap between, it looks like the description is missing (which is exactly what you thought), and it takes up vertical sceen space.

And indeed, a description is missing :)

Or rather, both methods are missing a description, and are followed by general text that applies to both. (If it was a single method's description it would be indented; compare ArgumentParser.exit.)

Vertical screen space isn't a finite resource or something we need to minimise, and can be useful to improve clarity/readability. And newlines are small.

For example, compare the use of bullet points on this page, where we could smush them into a concise paragraph.

https://docs.python.org/3/library/argparse.html

[nineteendo]

Maybe this is a better example (here the description clearly belongs to both methods):

[hugovk]

For that example, we could duplicate the description for each, and specialise it. I don't have a strong opinion, I think it might be clear enough as it is.

Back to the argparse one for a moment. That style is quite common in the Python docs: the text talks more generally about the module and introduces methods as it covers each concept. It would be a bigger discussion if we wanted to change that.

I don't think we can make sweeping changes here.

[nineteendo]

But here duplicating the description doesn't make sense:

[nineteendo]

Also note that we already do this in other cases (consistency would be welcome):

[AlexWaygood]

@nineteendo, I really appreciate your energy and enthusiasm for improving CPython, it's great to see. Please consider being a little more respectful of other people's time, though :-)

Hugo and I are both volunteers working on CPython in our free time outside of our regular jobs. Neither of us is paid to help maintain CPython (very few people are). We both maintain several other open-source projects in our free time, as well.

Hugo's already subscribed to this thread; he received a notification about your latest comments before you pinged him again a second time and I'm sure he'll respond when he has a moment. But it's pretty normal in open source to sometimes have to wait a few days for a response to a question. Folks often have other stuff going on in their lives than just CPython. Repeatedly pinging a maintainer after just half an hour without a response is, if anything, likely to make them get annoyed and switch off notifications entirely.

Again, I really appreciate your energy and enthusiasm and don't want to dampen that -- but the pace of open-source is sometimes a bit slower than what you seem to expect right now :-)

[nineteendo]

OK, understood. When should I post a reminder? One week, one month, ...?

[AlexWaygood]

If it's a simple question on an issue or a review request for a simple PR, I think sending a ping after a week should be fine. If it's a tough question that's going to require a long response, or a review request for a more complex PR, I generally try to wait at least two weeks before checking in again.

[hugovk]

Right, so we talked about this and I'm leaning towards preferring examples without newlines:

Instead of those with newlines:

Looking at the HTML, the one without is like this:

The description (for both) is in the shared dl's dd tag.

And the one with is like:

Here, the first dls dd is empty, and second's applies to both.

Semantically, the first one seems better? The description is closer to both dts.

So I think we'd accept a PR to change to this typing.IO style, at least for typing.

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?

---

Thanks Alex for sharing the advice on notifications. I will note the discussion above, extra research, and writing this up took longer than the 33 mins between the screenshots and the (now-deleted) ping message, so even if we'd got straight to it, I still wouldn't have been ready to reply :)

[nineteendo]

Thanks for taking the time anyway despite my impatience. I'll already make a pull request for typing.

[nineteendo]

I also couldn't find any specific accessibility advice either way for this

Could we create that for future additions to the docs? Then the situation doesn't get any worse.

We should decide for which directives it applies though. I wouldn't do it here for example:

[nineteendo]

Let's discuss this further here: https://discuss.python.org/t/group-definitions/52745.

[gvanrossum]

Vertical screen space isn't a finite resource or something we need to minimise, and can be useful to improve clarity/readability. And newlines are small.

I object to this claim. Vertical space is a finite resource -- scrolling sucks. Python itself was designed to minimize needless use of vertical space (no braces). When a single description applies to two preceding headings, the headings should not be separated by extra whitespace, to emphasize the grouping.

(Not saying that I endorse a mass changeover.)

[erlend-aasland]

Let's close this; the issue is too broad and there are no actionable items.