Documentation Community Team Meeting (December 2022)#
Date: 2022-12-05
Time: 20:00 UTC
This HackMD: https://hackmd.io/@encukou/pydocswg1
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#
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 :rocket:
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: https://github.com/python/devguide/pull/997
https://packaging.python.org/en/latest/glossary/
@CAM-Gerlach to improve the glossary. It can then be linked or copied to CPython docs.
PEP Workflow#
-
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 obselete PEPs to the SC to be formally rejected
We may need an obselete status?
Improve SEO for CPython docs#
(Hugo) OpenGraph metadata PRs:
CPython: ready for review, increases Google’s SEO score ~66->91 -> approved during and merged after the meeting :rocket:
Followup: tell Marc-André about use of logo without font
PEPs: TODO
Next meeting#
The docs team meets on the first Monday of every month.
First Monday of January 2023 is 2 Jan 2023. Will we all be ~~recovered from our New Year’s celebrations~~ back at Python work and ready to meet on that date?
January 9 2023 instead.
We have a recurring Google Calendar event for the meeting. Let Mariatta know your email address and she can invite you.