Editorial Board Decisions on Python Docs Editorial Board

``|`` or 'or' in parameter documentation

Tue, 11 Mar 2025 00:00:00 +0000

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.

Dead Batteries Docs

Tue, 11 Mar 2025 00:00:00 +0000

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.

Devguide Reorganization

Mon, 14 Oct 2024 00:00:00 +0000

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.

Style Guide recommendations

Wed, 28 Aug 2024 00:00:00 +0000

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

Timezone vs time zone

Thu, 18 Jul 2024 00:00:00 +0000

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 include slash and star

Fri, 12 Jul 2024 00:00:00 +0000

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.