Documentation Community Team Meeting (October 2022)¶
Date: 2022-10-03
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]
(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!
Roll call¶
Petr Viktorin /
@encukou
Adam T /
@AA-Turner
Ezio Melotti /
@ezio-melotti
Hugo van Kemenade /
@hugovk
Mariatta /
mariatta
Joannah /
nanjekyejoannah
Alex Waygood /
@AlexWaygood
CAM Gerlach /
@CAM-Gerlach
Pradyun /
@pradyunsg
Leam Hall
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.
Discussion¶
(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
:literal:
(`...`
) for docs.python.org?Less typing required, and no more errors caused by MarkDown-like
`...`
in rst documentsIt’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:
?Any projects using that? - yes –
ansible/ansible-lint
,scipy/scipy
(use a custom “autolink” role),micropython/micropython
,python-jsonschema/jsonschema
, etc
:literal:
is probably best, docs enthusiasts can help with adding proper rolesIf we don’t want to enable the default role, sphinx-lint has an optional checker for it (already enabled on
cpython
)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: python/pythondotorg#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
Pradyun: there are extensions (e.g. sphinxext-opengraph and built in to Sphinx.
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
C constants are documented as Python data
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
Next meeting¶
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.