Documentation Community Team Meeting (May 2024)

  • Date: 2024-05-07

  • Time: 19:00 UTC

  • This HackMD: https://hackmd.io/@encukou/pydocswg1

  • Discourse thread (for May)

  • 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])

  • Ned Batchelder / @nedbat

  • Petr Viktorin / @encukou

  • Ryan Duve / @ryan-duve

  • Eric

  • Hugo van Kemenade / @hugovk

  • CAM / @CAM-Gerlach

  • Erlend Aasland / @erlend-aasland

Introductions

Reports and celebrations

60 second updates on things you have been up to, questions you have, or developments you think people should know about. Please add yourself, and if you do not have an update to share, you can pass.

This is a place to make announcements (without a need for discussion). This is also a great place to give shout-outs to contributors! We’ll read through these at the beginning of the meeting.

Discussion

  • [Petr] Found some older PRs that didn’t get to Beta

    • Intersphinx in CPython docs – python/cpython#117540

      • Redistributors build docs while offline. This change shouldn’t be merged during beta. On May 8th main will be 3.14 alpha, it could be merged then.

      • Would also be good to map urls to local file paths for offline use. Open edX might have something like this to keep tests from breaking as different docs update at different rates.

    • Module page titles starting with a link to themselves – python/cpython#117099

      • Didn’t want to ping 29 code owners.

        • But they get pings a lot anyway.

      • A custom Sphinx plugin could prevent links in all section headers instead.

      • The plugin could also take care of links in sections/paragraphs to the sections/paragraphs.

        • This leads to the question of whether a human or an algorithm should make this decision.

      • Practically: merging this would be a good thing

      • Can we have a linter for links in section heads?

    • Merge versionchanged directives for the same version – python/cpython#116456

      • We agree unanimously that the status quo is better; we’ll close the PR.

      • Serhyi’s other contributions on the issue are great, though!

  • [Hugo] RTD migration work continuing: python/docs-community#5, have a WIP version and language selector at https://cpython-previews.readthedocs.io/en/main/

    • Manuel has done a lot of work on this (and Hugo has reviewed it)

    • The goal is to rebuild after every merge. Or a bit less, but more than the current daily builds

    • The plan is to move HTML first, but then look at other formats too.

  • [Petr] .. versionchanged:: next – do we want this in 3.14?

    • For changes that languish beyond a version cut

    • Also for backports?

    • Petr says he will build the tooling

    • Hugo is the release manager for 3.14 and 3.15 and will integrate it into the release tooling

    • Maybe in blurb release?

  • [Ned] - don’t forget to register for the Documentation Summit at PyCon, if you’re interested.

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.