Additional recommendations in the Style Guide https://github.com/python/devguide/pull/1377/

Summary

Discourse topic: How should we mark up multiple types in a type field?

Currently, the Python docs use | (pipe) character, similar to how you’d annotate a union of types:

:param p:
   A parameter that takes an int or a float argument.
:type p: int | float

However, the Sphinx docs says to use the word or:

:param p:
   A parameter that takes an int or a float argument.
:type p: int or float

The editorial board’s decision was requested on this matter via issue #7.

The editorial board discussed this over several meetings, our decision is to use the | symbol. We met with Adam Turner to discuss how this would be implemented in Sphinx. This is supported in the latest version of Sphinx and the CPython docs have been built using the latest Sphinx.

History of dead batteries: https://discuss.python.org/t/history-of-dead-batteries/68934

Documenting Dead batteries: https://discuss.python.org/t/documenting-dead-batteries/70652

PR: https://github.com/python/cpython/pull/126622

Summary

The PR adds a “Removed modules” page that lists modules which have been removed. Each module gets a page (with the original URL) that explains why the module is gone.

Refactoring the devguide into a Contribution Guide https://discuss.python.org/t/refactoring-the-devguide-into-a-contribution-guide/63409

Summary

We’ve started a large task to restructure the devguide to be more welcoming to non-code contributions.

Additional recommendations in the Style Guide https://github.com/python/devguide/pull/1377/

Summary

The Style Guide has been updated with new recommendations about author attribution (don’t include it) and pronunciation of dunder names (“an __init__, not a __init__).

Clarify timezone vs “time zone”: https://github.com/python/devguide/pull/1352

Summary

The CPython PR #118449 updates the spelling of “timezone” to “time zone”. There was a discussion on the PR that the “timezone” spelling is also acceptable and have been used within the CPython docs consistently. However, both Wikipedia and The Free Dictionary redirect “timezone” to “time zone”.

Using the two-word form “time zone” would help separate the concept from the “timezone” class in Python.

The Style Guide section on CPython Devguide has now been updated with the recommendation of using the two word time zone when referring to the real-world time concept, and to use the one word timezone with appropriate code markup when referring to a Python term.

Function signatures should include slash and star: https://github.com/python/devguide/pull/1344

Summary

If a function accepts positional-only or keyword-only arguments, include the slash and the star in the signature as appropriate.

.. function:: some_function(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):

Although the syntax is terse, it is precise about the allowable ways to call the function and is taken from Python itself.

The CPython Devguide has been updated to reflect this recommendation.