# Documentation Community Team Meeting (February 4, 2025) ## Roll call (Name / `@GitHubUsername` _[/ Discord, if different]_) - Carol Willing / `@willingc` - Petr Viktorin / `@encukou` - Daniele - Hugo van Kemenade / `@hugovk` - Joe Kaufeld / `@itsthejoker` - Keith - Maciek Olko / `@m-aciek` - Adam Turner / `@AA-Turner` - Jeff 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-theme` 2025.2 was released today. - We have narrowed supported Sphinx versions to only the latest; Sphinx 8.1. [cpython/python#125722](https://github.com/python/cpython/issues/125722) - We have revived efforts to generate Open Graph Protocol images ('social card previews') [python/docsbuild-scripts#147](https://github.com/python/docsbuild-scripts/issues/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](https://github.com/sphinx-doc/sphinx/issues/13105). - Translation progress since 14 December 2024: - zh-cn: 79.46% -> 80.64% - es: 62.38% -> 63.28% - pt-br: 53.79% -> 58.24% - zh-tw: 36.62% -> 37.00% - pl: 8.24% -> 9.44% - gr: 4.62% -> 4.83% - (please note that as of now completion tracking bases on paragraphs number, not [words](https://github.com/izimobil/polib/pull/166) number, and may not express the translation effort precisely) - [source](https://github.com/python-docs-translations/dashboard/compare/f015a5c401118514c12ae4c75328a201a46171c5...gh-pages) ## Discussion - The [Python Wiki](https://wiki.python.org/moin/Documentation) 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 - [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.python` in 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](https://github.com/sphinx-doc/sphinx/pull/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](https://github.com/sphinx-doc/sphinx/pull/13271). Options: - _`abstractmethod`_` write()` - _`abstract method`_` write()` - _`abstract`_` write()` * [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](https://www.sphinx-doc.org/en/master/usage/domains/python.html#directive-option-py-function-async) (Sphinx) - coro example: [`asyncio.sleep`](https://docs.python.org/3/library/asyncio-task.html#asyncio.sleep) - awaitable example: [`asyncio.gather`](https://docs.python.org/3/library/asyncio-task.html#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)](https://github.com/python/cpython/pull/129597#discussion_r1939080570) - [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](https://github.com/python/python-docs-theme/issues/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 - [Repo policy](https://devguide.python.org/developer-workflow/development-cycle/#organization-repository-policy) - [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](https://github.com/python-docs-translations)) - [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](https://github.com/python-docs-translations/dashboard/pull/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.