Documentation Community Team Meeting (February 4, 2025)¶
Roll call¶
(Name / @GitHubUsername [/ Discord, if different])
Carol Willing /
@willingcPetr Viktorin /
@encukouDaniele
Hugo van Kemenade /
@hugovkJoe Kaufeld /
@itsthejokerKeith
Maciek Olko /
@m-aciekAdam Turner /
@AA-TurnerJeff Jacobson
Blaise Pabon
Stan /
@StanFromIreland
Introductions¶
If there are any new people, we should do a round of introductions.
Introductions were made.
Reports and celebrations¶
60 second updates on things you have been up to, questions you have, or developments you think people should know about. Please add yourself, and if you do not have an update to share, you can pass.
This is a place to make announcements (without a need for discussion). This is also a great place to give shout-outs to contributors! We’ll read through these at the beginning of the meeting.
python-docs-theme2025.2 was released today.We have narrowed supported Sphinx versions to only the latest; Sphinx 8.1. cpython/python#125722
We have revived efforts to generate Open Graph Protocol images (‘social card previews’) python/docsbuild-scripts#147
Sphinx 8.2 (upcoming) will support a
:py:deco:cross-reference role. Thanks to Erlend Aasland and Alex Waygood for discussion sphinx-doc/sphinx#13105.Translation progress since 14 December 2024:
Discussion¶
The Python Wiki has a great deal of information, but much of it is badly outdated. For documentation-related pages, perhaps we ought remove these and redirect readers to d.p.o?
[Hugo] This came up recently. Marc-André was keen on keeping the wiki around. See https://discuss.python.org/t/remove-the-link-to-the-old-python-wiki/45316/13
[Carol] Would love to see the wiki go away completely. First, we should go through the d.p.o docs and remove references to the wiki. There’s a lot of out-of-date stuff, and it’s very confusing.
[Hugo] There are 22 instances of
wiki.pythonin the docs.People might be against deleting stuff.
Wikis are useful when they’re kept outdated. This one isn’t.
[Daniele] We have the same problem at work; people don’t want to throw it away but it’s mostly garbage and no one wants to go through it and make it better.
[Joe] Would it be useful to add a banner that explicitly says it’s unmaintained?
[Adam] There are some pages that are actively maintained. We can change it, but it’s onerous to make edits. Don’t know how to get history or get the content.
[Carol] I still think I have wiki access. After we get the links out of d.p.o, maybe we can go through the wiki, search for CPython and replace the info with links to docs. It’s a heavy lift to get rid of it.
There has been a long discussion on syntax and style for describing Python types in documentation, primarily taking place in the comments of a merged PR(!) in the Sphinx repository sphinx-doc/sphinx#13242. Do we wish to take a view here?
[Adam] In our docs, we can mark up types as static annotations in Python, or describe them in prose. Which do we want to standardize on? This was already discussed; are there any strong opinions we could take to the EB?
[Carol] Adam will go to the next EB meeting and hopefully it’ll get resolved.
Request for comment: how best to present abstract methods and classes? See sphinx-doc/sphinx#13271. Options:
abstractmethodwrite()abstract methodwrite()abstractwrite()
[Petr] Would it be possible to link that word to the glossary? (yes, we could)
Request for comment: how tightly should we draw the distinction between ‘async’, ‘awaitable’, and ‘coroutine’ callables? Note that Python’s documentation currently uses the latter two forms, but Sphinx only (currently) supports the former.
:async:option (Sphinx)coro example:
asyncio.sleepawaitable example:
asyncio.gather
[Petr] the distinction is confusing; ideally they should be made equivalent. But as long as they’re different, the docs should be precise
Python Project Documentation¶
Relating to docs.python.org, peps.python.org, devguide.python.org, etc.
[bswck] Track upstream->downstream translation block update alerts
Not discussed.
[Hugo] The availability directives are like:
.. availability:: Linux >= 2.6.27 with glibc >= 2.8. Should we automatically replace “>=” with “≥”, or rewrite as “version 2.8 or later” per Google, Microsoft and Apple style guides? python/cpython#129597 (comment)[Petr] I’d keep the directives compact; they’re not prose
[Joe] I’d use the single symbol
[Joe] The Unicode symbol was introduced in 1993, hopefully it renders well on near anything
[Petr] If there’s an issue with Unicode in some of the backends, we should fix that
[Hugo] Links back to homepage: python/python-docs-theme#217
[Adam] PEPs have a link to both python.org and peps.python.org. It’s probably best to have both links. If I’d have to choose, I’d have the icon either unlinked or go to
docs..[Petr] I’d rather have the link go to docs.python.org. It’d be more useful to folks who are visiting for the first time, and then have the docs homepage itself have a link to the standard python.org.
[Maciek] Moving into the inside of the Python GitHub organization
Python Docs Translation Dashboard repository?
Transifex automation repository?
or should we add a new organization for the around-translations-efforts?
[Petr] I recommend a new organization, where you’re an admin and can set it up however you want
[Adam] This could live under
python, the question is if it’s a good idea. It might make it easier to maintain.[Adam] For the dashboard, eventually we could move it to a folder in the docsbuild-scripts repo.
[Carol] I like both options, but note that we can always move repos from a translations organization to
python[Hugo] We might want to add the dashboard directly to the devguide. Maybe by having it generate a JSON file that devguide consumes?
[maciek] An organization is good for discoverability, and for shared maintenance in case the original maintainer steps down.
[Adam] Could we create a python-translations organization right now? (yes)
[Adam] Is the devguide the best place for the dashboard? Maybe we should have the dashboard on docs.python.org somewhere
[Maciek] Is displaying number of Sphinx build warnings in scope of Python Docs Translation Dashboard dashboard#45
[Hugo] Would it be useful to you as a translator? (yes)
[Adam] We don’t use nitpicky mode currently. Instinctively, going to the level of sphinx warnings is a bit much.
[Maciek] It could be a motivation for potential contributors.