Documentation Community Team Meeting (March 3, 2026)

Roll call

(Name / @GitHubUsername [/ Discord, if different])

  • Hugo van Kemenade / @hugovk

  • Trey Hunner / @treyhunner

  • Ned Batchelder / @nedbat

  • Ryan Duve / @ryan-duve

  • Maciej Olko / @m-aciek

  • Joe Kaufeld / @itsthejoker

Reports and celebrations

Discussion

  • [Ryan] Running man python3 shows documentation with unexpected newlines:

        -X showrefcount: output the total reference count and number
of used
        memory  blocks  when  the program finishes or after each
statement in the
        interactive interpreter. This only works on debug builds

    The newlines are not in the source, but it seems to appear in a few places. If this is an isolated bug, I think we can simply open an issue for it, but first I wanted to discuss whether others have thoughts on generally tracking how documentation is presented uniformly across all channels, e.g., PDF vs HTML, etc.

    We discussed that this may be due to manpage settings. python/cpython#145649 is open as an action item to highlight this.

  • [Ned] linklint: Pull request, discuss.python.org thread

    The Discourse thread complained about link underlines being distracting in the docs. We aren’t removing the underlines, but we can remove unnecessary links. Linklint started as a linter and fixer to update .rst files, but it works better as a Sphinx extension. Now it removes unneeded links from references during the build process. This means we don’t have to hard-code linking decisions in .rst files, and we don’t need to make churnful PRs to get rid of links. (Note: since the meeting, this has been completed.)

    One downside to the Sphinx extension: .rst has a syntax for making a reference but preventing the link. We have no syntax for a reference to insist on being a link even though the extension thinks it would be excessive.

    A possible next step is to remove links for “obvious” references like int, float, str, list and so on. We did not come to a conclusion about whether that would be a good idea or not.

  • [Hugo] import datetime as dt (python/cpython#145315)

    A discussion from 2023 suggested renaming datetime.datetime to datetime.DateTime to avoid confusion between the module, and the class inside the module. The topic suggested other renamings, deprecations, and aliases, which could involve breaking changes or warnings in lots of code.

    Hugo commented that he follows Adam Johnson’s recommendation of import datetime as dt and then you can unambiguously use dt.datetime, dt.time, and dt.timezone. He said he’s been using the pattern for several years and finds it much better than the alternatives. Terry suggested in the thread to use import datetime as dt in the docs.

    Others in the meeting were generally in favour of the PR: it’s docs only, doesn’t change the stdlib, doesn’t introduce warnings. People can continue to use whatever pattern they wish in their own code.

    Some used from datetime import datetime, time but thought import datetime as dt is better as it avoids the potential confusion, and thought it would be better for learners as well.

  • [Maciek] PDF builds broken due to SVGs (python/docs-community#182)

    • Currently, PDF builds are broken on 3.15 and 3.14 docs. There are several options on how we can fix it. It would be worth deciding which approach we should take.

    • [Hugo] Not keen on storing PDF graphics in the repository, as binary blobs. One idea, which would be quick to implement, is to gate on the PDF builder and not show any image, instead have some description if needed.

  • Transifex has a higher plan for ~6 months. Thanks to Adam T. and Hugo for making it possible!

    • [Hugo] Remember it’s a one-year trial. Towards the end of the year, we need to evaluate whether we wish to continue with it, and if so write up why.