PEP 655: Integrate feedback from S Pradeep Kumar #2323
Conversation
|
|
||
| Therefore: | ||
|
|
||
| :: |
There was a problem hiding this comment.
| :: | |
| .. code-block: python |
There was a problem hiding this comment.
According to Sphinx documentation, .. code-block:: python is equivalent to just :: in regular RST documents. And indeed using the former form appears to have no effect.
Strangely, neither form actually syntax-highlights Python code in color, at least in PEPs.
There was a problem hiding this comment.
Coloured syntax highlighting is planned via PEP 676, you can see a preview:
So a TypeScript code block would be useful for that particular snippet.
There was a problem hiding this comment.
Seconding Hugo -- the default for literal blocks is Python, but explicitness is always better, and it allows highlighting different languages, such as the TypeScript code in this PEP.
A
There was a problem hiding this comment.
Seconding Hugo and Adam as well. Furthermore, as that page also mentions, that default is fully configurable on a per-project and per-file basis, and we have discussed doing so in the past.
There was a problem hiding this comment.
I'll make a separate PR that marks the language for non-Python blocks
Presumably the PEP repo will be configured to use Python as the default syntax-highlighting language, so I won't bother to explicitly set the default language to Python in this specific PEP.
There was a problem hiding this comment.
Its still a good idea to explicitly specify the language in new PEPs, as it is more clear and consistent and we've discussed using a different default (though I think our current thinking, at least between @AA-Turner and myself, is to stick with python and modify any others accordingly), but it isn't critical.
There was a problem hiding this comment.
Explicit isn't always better than implicit :)
Because virtually all code is Python, and there are a lot of Python code blocks, I think we should allow the default :: for Python (and specify the language for other code blocks).
RST isn't easy. Just yesterday I read of someone ditching it for MyST: https://twitter.com/hynek/status/1493509644228173830
We should make writing documents fluent for PEP authors and not require them to stop and look up the syntax (at least I can't always remember the syntax off the top of my head) when the double colon shortcut is so easy.
(If there's a PEP with a lot of C, I think it would be fine switching the default for that PEP to C and then using ::.)
There was a problem hiding this comment.
I don't think there's harm in encouraging users to be explicit, but now that it seems we've at least informally settled on an approach going forward (use python as the default and update any non-python code blocks at least on active, process, etc PEPs), I agree with the sentiment that its overstepping to require all new PEP authors to explicitly annotate every code block (its what I would do myself in my own PEPs, but I can get a bit too carried away with purity at the expense of practicality sometimes).
Using .. language at the top of the file for PEPs like PEP 7 makes sense as well (particularly on old PEPs, to allow fixing their syntax highlighting in as little as one line rather than modifying every code block, reducing noise and churn), so long as PEP authors and editors are cognizant of it.
|
Happy to merge this whenever you want me to (unless you want Guido or Pradeep to have a look first). |
|
I'd be interested in leaving this open a few days in case @pradeep90 has any comments here, or the related typing-sig post, say until Thu 2/17 AoE. |
|
@davidfstr given Pradeep's approval are you happy for this to be merged? A |
|
Yes, I’m happy merging this |
No description provided.