Documentation Community Team Meeting (December 5, 2022)

Roll call

(Name / @GitHubUsername)

• Mariatta / @mariatta

• Petr / @encukou

• Ezio / @ezio-melotti

• Hugo van Kemenade / @hugovk

• CAM / @CAM-Gerlach

• Jim DeLaHunt / @JDLH

Reports and celebrations

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.

• Hugo’s promotion to Core Developer! 🎊

• @JDLH: A [packaging] docs issue I filed has been fixed, I feel like I made a (small) contribution. No clear list of permitted keys in “Declaring project metadata” specification issue #1101, fixed by Brett Cannon in PR #1168.

Discussion

Python Project Documentation

Relating to docs.python.org, peps.python.org, devguide.python.org, &c.

• (Hugo) Add release cycle chart to docs:

  • CSV PR was merged

  • charts PR ready for review -> merged during the meeting 🚀

  • demo

  • Followup: @CAM-Gerlach opened devguide issues for adding the additional development phase transition dates python/devguide#998 & a table of individual minor versions python/devguide#999

  • Followup: Hugo will check with it no JavaScript, and the remote hosting of https://unpkg.com/mermaid/dist/mermaid.min.js in case it goes down

    • -> No JS PR: python/devguide#997

• packaging.python.org/en/latest/glossary/

  • @CAM-Gerlach to improve the glossary. It can then be linked or copied to CPython docs.

PEP Workflow

• PEP 1 rewrite?

  • It was generally agreed that PEP 1 (and PEP 12) could use significant re-organization and trimming.

  • Petr suggests moving the author-facing help out of PEP 1/to the devguide

  • CAM mentions python/peps#2337 which proposes referencing the Sphinx reST primer instead of duplicating information there in PEP 12 and consolidating normative process guidance in PEP 1 and author-facing info in PEP 12/the devguide

  • @CAM-Gerlach will open a PR implementing that first step, linking the Sphinx reST primer in PEP 12 instead of duplicating that information

  • CAM also mentions the devguide’s reST primer is essentially just a less-up-to-date copy of the Sphinx one; it should be revised to link to it and focus on CPython-specific guidance. This issue was already open as python/docs-community#57, which was moved to python/devguide#1000, where @CAM-Gerlach will work on it

• Final PEPs and the canonical docs banner link

  • python/peps#2719 will improve the existing banners directing users to the canonical docs for Final PEPs added in python/peps#2702 to be sticky at the top; @CAM-Gerlach to submit PR

  • We can start going through Final PEPs and systemically marking them with the new banner as appropriate

  • @CAM-Gerlach will submit PRs for python/peps#2872 to mark old implemented Accepted PEPs as Final, and will add banner in the process

  • We might need a checklist for marking PEPs Final

    • e.g.: is it documented outside the PEP? Add a note?

  • @CAM-Gerlach will open an issue to discuss adding checklists for new, Approved/Rejected and Final PEPs (opened as python/peps#2937)

• Status for PEP 659?

  • @CAM-Gerlach will open issue proposing a list of obsolete PEPs to the SC to be formally rejected

  • We may need an obsolete status?

Improve SEO for CPython docs

• (Hugo) OpenGraph metadata PRs:

  • devguide: merged, increases Google’s SEO score 91->100

  • CPython: ready for review, increases Google’s SEO score ~66->91 -> approved during and merged after the meeting 🚀

  • Followup: tell Marc-André about use of logo without font

  • PEPs: TODO