Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add notes from 2022-10 #61

Merged
merged 3 commits into from
Oct 17, 2022
Merged

Add notes from 2022-10 #61

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b478ac4
Add notes from 2022-10
encukou Oct 4, 2022
4e974f4
Apply suggestions from code review
encukou Oct 5, 2022
17c6628
Apply suggestions from code review
encukou Oct 17, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 91 additions & 0 deletions docs/monthly-meeting/2022-10.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
# Documentation Community Team Meeting (October 2022)

- **Date:** 2022-10-03
- **Time:** [19:30 UTC](https://arewemeetingyet.com/UTC/2022-10-03/19:30/Docs%20Meeting)
- **This HackMD:** https://hackmd.io/@encukou/pydocswg1
- [**Discourse thread**](https://discuss.python.org/t/19070) for October
- **Calendar for future meetings:** (send your e-mail to Mariatta for a calendar invitation)
- **How to participate:**
- Go to [Google Meet](https://meet.google.com/dii-qrzf-wkw) 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](https://www.python.org/psf/codeofconduct/).
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! https://discuss.python.org/t/recordings-available-for-python-docs-diataxis-workshop/19518
encukou marked this conversation as resolved.
Show resolved Hide resolved


## 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](https://github.com/python/cpython/pull/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
Copy link

@bskinn bskinn Oct 4, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If I understand what the goal is here, this is already possible. When you declare intersphinx_mappings in conf.py, you can pass a tuple to the second argument. Sphinx will walk through each element of the tuple and work with the first successfully-found objects.inv. (You can still use None as one of the tuple elements to check the default web location.)

See "Multiple targets for the inventory" in the intersphinx docs.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is what we talked about, but Petr apparently wanted to propose something a little different.

Copy link

@bskinn bskinn Oct 4, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Interesting...I'm curious now what he's wanting.

Just about anything beyond that that I can think of should be handle-able by some dynamic code in conf.py.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The distro doesn't really “own” conf.py, and would have to patch it. That's ugly and fragile/tedious. (Also note that when building docs for offlline use, we want the Intersphinx links to point to other offline (locally installed) docs, rather than to the Web.)
So I would prefer an external way (e.g. file named by environment variable) to specify that a given URL should be replaced by a local file. But that sounds like a “selfish” request from a distro, so I'm wary of suggesting it before I have time to contribute an implementation.
However, it could pave the way to support for building & interlinking multiple docs projects locally, for offline use: if projects could specify the “publish URL” in conf.py, Sphinx could also update the URL→file mapping. Perhaps that would be useful more widely.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nod, I see what you mean -- the need is potentially general, so better for it to be an official Sphinx feature rather than a conf.py hack; and, better just overall for it not to be a conf.py hack.

Thanks for the details!

Copy link
Member

@CAM-Gerlach CAM-Gerlach Oct 5, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I, I see. That makes more sense now.

As a short term approach, we could just read in some env variable in the conf.py and use that to set the file path—it isn't ideal, but it isn't that hacky. Certainly long term I imagine it would be nice to have a better mechanism, but the timeline for distros adopting a Sphinx version with it might not be short or consistant with adopting the relevant Python version(s) with Intersphinx.

if projects could specify the “publish URL” in conf.py, Sphinx could also update the URL→file mapping.

Hmm, though projects would ultimately still need a way to find the other projects' conf.pys, and have some sort of mapping to them that the original project can specify. I imagine that's possible on the distro side, but I'm not sure if there's a generalized solution beyond that.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FYI, see python/cpython#97781 for the initial motivating case

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thinking about it some more, just being able to override intersphinx_mapping with some arbitrary locally set value would give you both things you want—you can set both the source .inv location and the target of the generated links to resolve to a local file location as well as a HTTP(S) URL. Right now, we could add a bit of code in conf.py that reads this value in from an env variable if present and evals it, overriding the configured default.

A longer term Sphinx-level solution could perhaps be some way, e.g. a config file, to map URLs to source .invs and target docs locations.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll open an issue, PR and Discourse thread to summarize all this and continue discussion, as soon as I get a free moment during the sprints.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO:
For the motivating example: if Python wants to adopt PyPA terminology in its own docs, we should copy the definitions over.
For distros (speaking with my Python hat on): don't worry too much about them. If they care, they can patch/workaround, and then iterate toward a better solution.

* 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?
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* (Ezio) Should we enable the default role and alias it to `:literal:` (`` `...` ``) for docs.python.org?
* (Ezio) Should we enable the default role (`` `...` ``) for docs.python.org?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As I understand it, the default role is already enabled, it's just aliased to... something that shows up as italics.
So it would be more correct this way?

Suggested change
* (Ezio) Should we enable the default role and alias it to `:literal:` (`` `...` ``) for docs.python.org?
* (Ezio) Should we alias the default role (`` `...` ``) to `:literal:` for docs.python.org?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indeed "enable" might not be the best word. What I meant is "allow the use of the default role", not actually enabling it in the code or configuration.

That's the first step. If we do decide to allow it, then the next step is bikeshedding on what the best aliasing would be. I tried to better convey this by separating the two steps in this section.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To me, it dosesn't make sense to allow using it before we decide what it should mean...
Anyway, let's keep the original wording? These are meeting notes, not a specification -- it can be imprecise.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just to note, for now, @hugovk fixed current usages and had Sphinx-Lint flag future ones in python/cpython#97998 (which I'm currently working to backport to 3.11 and 3.10).

* Less typing required, and no more errors caused by MarkDown-like `` `...` `` in rst documents
encukou marked this conversation as resolved.
Show resolved Hide resolved
* 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
* We could also alias it to `:any:`?
encukou marked this conversation as resolved.
Show resolved Hide resolved
* Any projects using that? - [yes](https://github.com/search?l=Python&q=filename%3Aconf.py+default_role+%3D&type=Code) -- `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 already emits an error for single backticks -- making the error message there more friendly might improve usability for new contributors a great deal. (The messsage is currently just "Default role used".)
encukou marked this conversation as resolved.
Show resolved Hide resolved

* [Docs preview PR](https://github.com/python/cpython/pull/92852) 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
* https://github.com/python/pythondotorg/issues/1691
encukou marked this conversation as resolved.
Show resolved Hide resolved
* 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. https://pypi.org/project/sphinxext-opengraph/ / https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#html-metadata). re.
* e.g. Google Lighthouse audits https://web.dev/measure/?url=https%3A%2F%2Fdocs.python.org%2F3%2Flibrary%2Fcsv.html%3Fhighlight%3Dcsv%23module-csv
encukou marked this conversation as resolved.
Show resolved Hide resolved
* 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
encukou marked this conversation as resolved.
Show resolved Hide resolved

* [C constants are documented as Python data](https://github.com/python/cpython/issues/96996)
* Probably best to break this
* Sphinx could get some support for migration

* (Hugo) Petr might want to talk about ["Broken references in Sphinx docs"](https://discuss.python.org/t/broken-references-in-sphinx-docs/19463)?
* 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.
1 change: 1 addition & 0 deletions docs/monthly-meeting/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,3 +19,4 @@ Monthly reports in reverse chronological order.
Jul 2022 <2022-07.md>
Aug 2022 <2022-08.md>
Sep 2022 <2022-09.md>
Oct 2022 <2022-10.md>