-
-
Notifications
You must be signed in to change notification settings - Fork 30.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Don't needlessly repeat Sphinx directives #118030
Comments
@AlexWaygood, what should we do here? |
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 And the suggestion: only one The original means we have consistent semantics, which is important for non-visual users with screen-readers or braille displays. |
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 |
Sorry, I should have clarified this: the description from the second method belongs to BOTH methods:
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. |
Thanks for the clarification.
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 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. |
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 I don't think we can make sweeping changes here. |
@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 :-) |
OK, understood. When should I post a reminder? One week, one month, ...? |
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. |
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 And the one with is like: Here, the first Semantically, the first one seems better? The description is closer to both So I think we'd accept a PR to change to this 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 :) |
Thanks for taking the time anyway despite my impatience. I'll already make a pull request for |
…Kwargs` in `typing.rst` (pythonGH-118154) (cherry picked from commit 78ba4cb) Co-authored-by: Nice Zombies <nineteendo19d0@gmail.com>
Let's discuss this further here: https://discuss.python.org/t/group-definitions/52745. |
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.) |
Let's close this; the issue is too broad and there are no actionable items. |
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
Renders with a newline:
Could be changed to:
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 matchesLinked PRs
ParamSpecArgs
andParamSpecKwargs
intyping.rst
#118154ParamSpecArgs
andParamSpecKwargs
intyping.rst
(GH-118154) #118155The text was updated successfully, but these errors were encountered: