Introduce "type names" section to the style guide#1828
Conversation
Resolves python#1821 This enhancement to the style guide was motivated by a desire to resolve some inconsistent phrasing in the docs, which caused some disagreement in a CPython docs PR. The new section describes guidance for how type names should be documented. Class references or unlinked class styling are preferred, and other styles are described for use only when they are superior to the class name.
Documentation build overview
4 files changed± index.html± documentation/index.html± versions/index.html± documentation/style-guide/index.html |
Co-authored-by: Stan Ulbrych <stan@python.org>
| Type names | ||
| ========== | ||
|
|
||
| When writing the names of types in prose, write the name of the type | ||
| exactly as it appears in source, styled as a class reference or an unlinked | ||
| class. For example, refer to dict as ``:class:`dict``` or ``:class:`!dict```. | ||
|
|
||
| Links should be used according to the :ref:`guidance on links <links>`. | ||
|
|
||
| Some type names are commonly understood ideas or nouns outside of Python. | ||
| For example, "tuples" are a general programming concept, as distinct from the | ||
| ``tuple`` type. When referring to general ideas, do not style the relevant word | ||
| as a type. | ||
|
|
||
| Many types have descriptive names which do not exactly match their type | ||
| name. For example, "context variables" describes ``contextvars.ContextVar``, | ||
| and "partial function" may be used to describe an application of | ||
| ``functools.partial``. Use these names only when they serve to clarify the text | ||
| better than the type name itself would, and put them in lowercase. |
There was a problem hiding this comment.
I suggest moving this entry after the simple language one, and perhaps also after the charged terminology one as well.
There was a problem hiding this comment.
Should the "Specific words" section above it also move? I thought it made sense to put these together, and I still do. What would you say to moving both of these?
I could do it here (pragmatic and easy, but my least favorite way), do a precursor PR to move "Specific words" down, or do a follow-up PR.
There was a problem hiding this comment.
Moving "Specific words" sounds okay to me, no preference whether in this PR or another.
There was a problem hiding this comment.
I'll do it here.
I'm used to smaller projects with relatively much more review bandwidth per PR. I'm adjusting a bit for cpython and related projects. 🙂
There was a problem hiding this comment.
3c5e2c7 pushes them down, and as "proof" of my work making no other changes, the git diff selects the text which I did not cut-and-paste.
I did introduce one extra newline, which seemed like it was missing for a section-break.
The "specific words" section and the new "type names" which follows it are now below the "simple language" and "charged terminology" sections. No content was changed in the course of this. (NB: git's diff algorithm selects opposite pieces of text based on size)
| exactly as it appears in source, styled as a class reference or an unlinked | ||
| class. For example, refer to dict as ``:class:`dict``` or ``:class:`!dict```. | ||
|
|
||
| Links should be used according to the :ref:`guidance on links <links>`. |
There was a problem hiding this comment.
/home/runner/work/devguide/devguide/documentation/style-guide.rst:155: WARNING: undefined label: 'links' [ref.ref]
There was a problem hiding this comment.
Shouldn't that link to the section title? I feel certain that this worked for me.
I just added an explicit anchor, on the assumption that I got confused and forgot how sphinx handles section-names.
There was a problem hiding this comment.
Shouldn't that link to the section title?
You have a :ref:, not a regular link `guidance on links `_ (I don't remember if we still need the #) is what you're thinking about
I'm +1 for an explicit reference however, I think it's far more future proof. But can we rename it to something a little more useful, like links-style-guide.
There was a problem hiding this comment.
Ah, so that we can use it from outside of the style-guide! Yes, I like that, but mildly prefer style-guide-links (namespace first).
I've added a co-authored commit. 🙂
Give it some namespacing so that it can be referenced more fluently from other parts of the devguide. Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
4 participants
Resolves #1821
This enhancement to the style guide was motivated by a desire to resolve some inconsistent phrasing in the docs, which caused some disagreement in a CPython docs PR.
The new section describes guidance for how type names should be documented. Class references or unlinked class styling are preferred, and other styles are described for use only when they are superior to the class name.
The issue has no comments, but I introduced the idea in the docs community where it got some positive feedback.
The discussion there helped to shape the issue, which has some basic 👍 s from a couple of core devs.