Documentation Community Team Meeting (October 2022)

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?

If enabled, what should it be aliased to?

  • We could also alias it to :any:?

    • Any projects using that? - yesansible/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: 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.

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