-
-
Notifications
You must be signed in to change notification settings - Fork 25
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Co-authored-by: Hugo van Kemenade <[email protected]>
- Loading branch information
Showing
2 changed files
with
89 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,88 @@ | ||
| # Documentation Community Team Meeting (August 2024) | ||
|
|
||
| - **Date:** 2024-08-06 | ||
| - **Time:** [19:00 UTC](https://arewemeetingyet.com/UTC/2024-08-06/19:00/Docs%20Meeting) | ||
| - **This HackMD:** <https://hackmd.io/@encukou/pydocswg1> | ||
| - [**Discourse thread**](https://discuss.python.org/t/documentation-community-meeting-tuesday-6th-august-2024/59599) (for August) | ||
| - [**Meeting reports**](https://docs-community.readthedocs.io/en/latest/monthly-meeting/) (the latest one might be an [**unmerged PR**](https://github.com/python/docs-community/pulls)) | ||
| - **Calendar event:** (send your e-mail to Mariatta for an invitation) | ||
| - **How to participate:** | ||
| - Go to [Google Meet](https://meet.google.com/dii-qrzf-wkw) and ask to be let in. | ||
| - To edit notes, click the “pencil” or “split view” button on the [HackMD document](https://hackmd.io/@encukou/pydocswg1). | ||
| 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](https://www.python.org/psf/codeofconduct/). | ||
| Please take a second to read through it! | ||
|
|
||
| ## 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 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)* | ||
|
|
||
| ## Next meeting | ||
|
|
||
| The docs team generally meets on the first Tuesday of every month around 19:00-ish UTC. | ||
|
|
||
| We have a recurring Google Calendar event for the meeting. | ||
| Let Mariatta know your email address and she can invite you. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters