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. 🙂
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)
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.