Documentation Community Team Meeting (September 2023)#
Date: 2023-09-05
Time: 19:00 UTC
This HackMD: https://hackmd.io/@encukou/pydocswg1
Discourse thread (for September)
Meeting reports (the latest one might be an unmerged PR)
Calendar event: (send your e-mail to Mariatta for an invitation)
How to participate:
Go to Google Meet and ask to be let in.
To edit notes, click the “pencil” or “split view” button on the HackMD document. You need to log in (e.g. with a GitHub account).
By participating in this meeting, you are agreeing to abide by and uphold the PSF Code of Conduct. Please take a second to read through it!
Roll call#
(Name / @GitHubUsername / Discord if different)
CAM Gerlach /
@CAM-GerlachDaniele Procida /
@EvilDMPPetr Viktorin /
@encukouAdam Turner /
@AA-TurnerHugo van Kemenade /
@hugovkMaciej Olko /
@m-aciek/@m_aciekRyan Duve /
@ryan-duveMarcus Sherman /
@betteridiotErlend Aasland /
@erlend-aaslandEge Akman /
@egeakmanEzio Melotti /
@ezio-melotti
Introductions#
Maciej, from Poland, works on Polish translation
Reports and celebrations#
[Hugo] docs.python.org now has a dark theme! 🌒
[Hugo] Little things can be big things: I added a shortcut at the top of the datetime docs to take you directly to the percent formatting codes. People are happy!
[Adam] Six releases of Sphinx!
[Adam] New PEP helper & validator (
check-peps.py)[Adam] Datamodel headings for readability
[Adam] Work to remove references to Distutils in the documentation ahead of the 3.12.0 release
Discussion#
[Hugo] python-docs-theme:
Need a release of 2023.8 to fix some dark theme bugs: python/python-docs-theme#152
Have a PR ready to release using Trusted Publishers, need someone to set it up on PyPI: python/python-docs-theme#148
These are both waiting on people who can make releases. Adam: should we review the group of people who can make releases, and look to expand it? Potentially ties in to a Python organisation on PyPI.
[Ege/Hugo/CAM] Updates and discussion on Plausible hosting:
PSF folks opposed to self-hosting
Paid hosting is a little expensive
We got a 15% discount from them, which would be $1400-$1500 yearly
People brought up several motivating use cases already for this, including:
Translation prioritization for languages/pages
Automated translations
Determine how many people use backported branches
Determining if old pages are still needed/used
Potentially determine common broken links, maybe even fragment ids?
Prioritisation for documentation
If the budget is available, why not use it?
Next steps: CAM to write to Deb from the PSF with a summary of this discussion
[Maciej] Translations platform – trying to initiate discussion (Discourse thread)
Transifex has cut off shared memory (between projects) for open source tier, Rafael from Brazilian Portugese team implemented a workaround
Weblate – based on Django, open license, used by PyPI
The POC of Python docs translations/Weblate integration is functional, I’m working on improving it
Python docs don’t fit into free open source tier on Weblate – the initial proposition is 1500€/year (50% discount)
There is an option to self-host a Weblate instance
(Both platforms support using machine learning translation tools)
Next steps: Contact the PSF with assistance from CAM
[Ege] New bootstrapper for starting new Python docs translations
Issues with the current tool:
Unmaintained / inactive
Uses third-party modules
Next steps: Add a link from the devguide to this repository
[CAM] Quick update on reStructured Data
Summary
Mechanism to extract, process and output structured, machine-readible data from the Python docs
Initial focus on deprecations/removals per user requests, then additions/changes and finally other annotations (supported platforms, stable ABI, audit events, etc.)
Output a JSON per version and language for tool and API consumption
Also output tables of all/specific deprecations/removals (or other changes) in the What’s New and on a new dedicated Deprecations/Removals page.
Progress
Further considerable work on design document, schema, etc.
Developed initial working implementation and prototyped/tested most planned features
Discussed current approach at some length with Adam and currently making some significant changes based on his feedback
Next steps: Re-scoping to focus on the basic features needed
Learn more
[Hugo] Python 3.12.0 is out on 2023-10-02! Any finishing touches needed for What’s New In Python 3.12?
[CAM] Was planning to finish this at the core dev sprints, but didn’t realize the final release date was so much earlier than last year
[CAM] Wanted to be able to use the new reStructured Data directive to list deprecations, removals, additions and changes in the appropriate places following the existing format, but too late for that now
[CAM] May be able to use it to help guide the process, but timeline is going to be tight
[Daniele] How much appetite/consensus is there for an iterative workflow? Discussion in Discord
Petr and Daniele can adapt the Discord messages into a Discourse thread and post that for further feedback and consensus
Next meeting#
The docs team generally meets on the first Tuesday of every month.
We have a recurring Google Calendar event for the meeting. Let Mariatta know your email address and she can invite you.