# Documentation Community Team Meeting (August 6, 2024)


## Roll call

(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`

## 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.
  - Test: <https://cpython-previews.readthedocs.io/en/main/>
  - [python/docs-community#5](https://github.com/python/docs-community/issues/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](https://github.com/readthedocs/readthedocs.org/issues/11319)
    - Design doc: [readthedocs/readthedocs.org#11507](https://github.com/readthedocs/readthedocs.org/pull/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](https://github.com/python/cpython/issues/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](https://github.com/python/cpython/issues/92564)
  - A related core-workflow issue: [python/core-workflow#468](https://github.com/python/core-workflow/issues/468)
  - Moving deprecations into include files: [python/cpython#122085](https://github.com/python/cpython/issues/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](https://github.com/python/devguide/issues/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.

[#118891 Slow actions for doc builds](https://github.com/python/cpython/issues/118891)

### PEP Workflow

- [PEP 750: Tag strings for writing domain specific languages](https://github.com/python/peps/pull/3858) FYI

## Follow-ups from previous meeting(s)

*[Monthly reports archive](https://docs-community.readthedocs.io/en/latest/monthly-meeting/index.html)*