(Name / @GitHubUsername [/ Discord, if different])
- Hugo van Kemenade /
@hugovk - Ezio Melotti /
@ezio-melotti - Trey /
@treyhunner - Manuel /
@humitos - Ned Batchelder /
@nedbat - Petr Viktorin /
@encukou - Usman
- Carol /
@willingc - Daniele /
@EvilDMP
- [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.
- Test: https://cpython-previews.readthedocs.io/en/main/
- python/docs-community#5
- 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.
- Issue: readthedocs/readthedocs.org#11319
- Design doc: readthedocs/readthedocs.org#11507
- [Carol] That's way further ahead than I thought. Thank you!
[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
- python/devguide#1359
- [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.