Documentation Community Team Meeting (August 6, 2024)¶
Roll call¶
(Name / @GitHubUsername [/ Discord, if different])
Hugo van Kemenade /
@hugovkEzio Melotti /
@ezio-melottiTrey /
@treyhunnerManuel /
@humitosNed Batchelder /
@nedbatPetr Viktorin /
@encukouUsman
Carol /
@willingcDaniele /
@EvilDMP
Reports and celebrations¶
[Manuel] Moving the docs to Read the Docs
Several reasons: be more open (let everyone see if the builds failed, how the builds work); faster builds;
A test is already working for pull requests. Only PRs that touch documentation are built.
In the last 1-2 months, we’ve been working on the language and version selector. In the current process this is added at build time from a JSON file, RTD does that at serve time with Javascript so even old versions of the docs link to current versions.
We’ve been working to not losing what we already have but also not get rid of RTD features.
3.13 or 3.14 is the version we’ll migrate first, to get a feel for the workflow. All other versions will be served by python.org for now. Then we’ll migrate one version at a time.
[Trey] Will this enhance the search? [Manuel] There have been many improvements in RTD search lately. Traditionally RTD overwrites Sphinx search entirely with server-side (Elastic Search) search. Now there’s a way to choose RTD or Sphinx search from the docs theme. There’s also a person who said they’re working on the Sphinx search engine.
[Trey] So there won’t be a change on day one.
[Carol] For the PR previews, is there an option to link to the most changed file in the PR? [Manuel] We’re working on it, don’t know the details. The idea is to perform a diff and determine what changed, and link to it directly.
Design doc: readthedocs/readthedocs.org#11507
[Carol] That’s way further ahead than I thought. Thank you!
Discussion¶
[Ezio] Deprecations in the What’s New file - replacing the list of deprecations with a table
[Hugo] We previously talked about putting deprecations in include files. We have that now: https://docs.python.org/3/deprecations/index.html
Compare https://pillow.readthedocs.io/en/stable/deprecations.html and https://docs.pytest.org/en/stable/deprecations.html
Some notes compiled after the meeting:
improving deprecation notes: explain how to replace the deprecated API, either in the note, or in a section at the bottom of the module’s doc
duplication: ensure that the deprecation notes only exist in a single place without duplication (links to it and includes in multiple places are fine)
discoverability: making sure that people can easily find what is being deprecated and removed, and how to fix it
future-proofing: make sure these info are not completely removed from the latest docs (a link to older versions is fine)
layout: list vs table (see python/cpython#122652), next step is to create a table as a proof of concept to see what works best
Some additional links:
python-dev thread from a decade ago: https://mail.python.org/pipermail/python-dev/2011-October/114199.html (some of these things are fixed, some are no longer relevant, some still need work)
Enforcing the use of deprecated-removed: python/cpython#92564
A related core-workflow issue: python/core-workflow#468
Moving deprecations into include files: python/cpython#122085
Next step: add a demo of how the table would look
[Ezio] Defining and documenting a procedure to ensure that we follow up on additional tasks brought up in review
[Hugo] If someone says “let’s do this”, they should be in charge of who’s going to do it
[Ezio] There’s a “diffusion of responsibility”, we should define who should go and open the issue to follow up. The proposal is that the PR author should be in charge – either volunteer to follow up or find other actors to do it.
[Carol] One thing we’ve done on other projects is that the person who proposes additional work should open that issue; then it’s fair game for anyone to pick it up.
[Ezio] One reason I mentioned the author of the PR is that someone could come and see an issue, but they don’t have the context that the PR author has.
#118891 Slow actions for doc builds