Documentation Community Team Meeting (October 2022)#
Time: 19:30 UTC
This HackMD: https://hackmd.io/@encukou/pydocswg1
Discourse thread for October
Calendar for future meetings: (send your e-mail to Mariatta for a calendar 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]
(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. Please take a second to read through it!
Petr Viktorin /
Adam T /
Ezio Melotti /
Hugo van Kemenade /
Alex Waygood /
CAM Gerlach /
Quick updates - Introductions#
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.
(CAM) Should we enable Intersphinx support on the CPython 3.12 docs? It would primarily benefit porting/syncing docs from other places, like PEPs, importlib metadata/resources, and packaging, but could cause problems for downstreams (e.g. Linux distros) building the docs from source without network access. See python/cpython#97785.
Allows single source of truth for definitions, etc.
Not offline buildable
Petr: would like Sphinx to provide a directory to reference local inv files to do offline builds
next steps: Cam to open a PR in 3.12, also a Discuss thread. Petr to open an issue in Sphinx.
Docs to support Sphinx 5.x. @CAM-Gerlach wants to add a CI workflow during the sprint week for the oldest-supported version of Sphinx.
Adam will work on sphinx support on python-docs-theme
(Ezio) Should we enable the default role and alias it to
`...`) for docs.python.org?
Less typing required, and no more errors caused by MarkDown-like
`...`in rst documents
It’s not used for anything, so we could use it instead of (or as an alias to)
Unless we mass edit the docs (to switch to single backticks), it might lead to inconsistencies
If enabled, what should it be aliased to?
We could also alias it to
Any projects using that? - yes –
scipy/scipy(use a custom “autolink” role),
:literal:is probably best, docs enthusiasts can help with adding proper roles
If we don’t want to enable the default role, sphinx-lint has an optional checker for it (already enabled on
Docs preview PR is still blocked on Ee allowing access to the Netlify account, which could help Adam’s concerns above
Mariatta to ping ee again
Joannah might want to talk about SEO for the docs
docs.p.o SEO is not great
discussed in PSF channel
what are tools to improve? How to improve?
Do we have the skills for improving SEO, or do we need external expert? It may be possible for The PSF to help fund it, we can request it.
Existing issue: https://github.com/python/pythondotorg/issues/1691
Adam: From Sphinx perspective: there is no SEO there. no expertise from Sphinx.
Petr: we may need a paid expert to handle this
Hugo: add more metadata. There are best practises.
CAM: Google has some tools that will tell you what’s missing. Some of the improvements could be done in the theme.
Mariatta: We have a lot of inbound links
CAM: It seems like we should be able to do a lot of this.
Let’s do the low-hanging fruit first
First, we need to come up with a list of issues to improve SEO
Then we can see if we need to get an expert paid if need be to advise
Probably best to break this
Sphinx could get some support for migration
(Hugo) Petr might want to talk about “Broken references in Sphinx docs”?
Discussed for a bit after the meeting ended
The docs team meets on the first Monday of every month.
We have a recurring Google Calendar event for the meeting. Let Mariatta know your email address and she can invite you.