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]

  • (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!

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.

• Videos for the Diataxis workshop were published!

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 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:?

  • 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 roles

• If 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

• python/pythondotorg#1691

  • 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

  • Pradyun: there are extensions (e.g. sphinxext-opengraph and built in to Sphinx.

  • e.g. Google Lighthouse audits

  • 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.