From 5e5b65856150e860605eb18a156c59d6167aece0 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Thu, 12 Sep 2024 18:08:34 +0300 Subject: [PATCH 1/2] Add September 2024 meeting notes --- docs/monthly-meeting/2024-09.md | 89 +++++++++++++++++++++++++++++++++ docs/monthly-meeting/index.rst | 1 + 2 files changed, 90 insertions(+) create mode 100644 docs/monthly-meeting/2024-09.md diff --git a/docs/monthly-meeting/2024-09.md b/docs/monthly-meeting/2024-09.md new file mode 100644 index 0000000..34513df --- /dev/null +++ b/docs/monthly-meeting/2024-09.md @@ -0,0 +1,89 @@ +# Documentation Community Team Meeting (September 2024) + +- **Date:** 2024-09-03 +- **Time:** [19:00 UTC](https://arewemeetingyet.com/UTC/2024-09-03/19:00/Docs%20Meeting) +- **This HackMD:** +- [**Discourse thread**](https://discuss.python.org/t/documentation-community-meeting-tuesday-3rd-september-2024/62175) (for September) +- [**Meeting reports**](https://docs-community.readthedocs.io/en/latest/monthly-meeting/) (the latest one might be an [**unmerged PR**](https://github.com/python/docs-community/pulls)) +- **Calendar event:** (send your e-mail to Mariatta for an 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 + +(Name / `@GitHubUsername` *[/ Discord, if different]*) + +- Daniele Procida / @EvilDMP +- Hugo van Kemenade / @hugovk +- Trey / @treyhunner +- Manuel / `@humitos` +- Melissa / @melissawm +- Petr Viktorin / @encukou +- Ryan / `@ryan-duve` + +## Discussion + +- [Hugo] + - As a RM, logged into the docs server, and fixed a bunch of stopped jobs + - It would be nice to have 2 cron jobs -- one for HTML (fast), one for PDFs (slow) + - We have a bus factor for the repo; only 2 active people; we should give access to more people & we should give Adam access to the build server + - Separately, we want to move HTML to Read the Docs, while keeping the ability to build them separately + +- Dropping PDF builds - should we drop one of the formats (A4/letter)? + - [Danilel] PDF is used for e-mail from sales, and for air-gapped environments. + - [Melissa?] If drop both, would need alternative, such as single page HTML [Petr?] And give some love to the print styles + - [Trey] Is HTML faster to build? [Hugo] Yes, about 3 mins for HTML compared to 30 min to 2 hours for full set: + | Start | Language/version | Build | + | :--------------: | :--------------: |------: | + | 2024-09-02 23:53 | zh-tw/3.13 | 1h 44m | + | 2024-09-03 01:39 | zh-cn/3.13 | 1h 32m | + | 2024-09-03 03:13 | uk/3.13 | 3m | + | 2024-09-03 03:17 | tr/3.13 | 1h 45m | + | 2024-09-03 05:04 | pt-br/3.13 | 40m | + | 2024-09-03 05:45 | pl/3.13 | 33m | + | 2024-09-03 06:20 | ko/3.13 | 54m | + | 2024-09-03 07:16 | ja/3.13 | 1h 23m | + | 2024-09-03 08:40 | it/3.13 | 32m | + | 2024-09-03 09:13 | id/3.13 | 42m | + | 2024-09-03 10:25 | es/3.13 | 1h 59m | + | 2024-09-03 12:25 | en/3.13 | 32m | + - [Manuel] What's the frequency? [Hugo] 24 hours or more + - [Manuel] Can we build PDFs less often? People who download them probably read them offline. + - [Melissa] What about rinohtype? [brechtm/rinohtype](https://github.com/brechtm/rinohtype) [Daniele] It's as slow as LaTeX; the typesetting quality should be comparable. + - [Melissa] For NumPy/SciPy there's nothing that can replace LaTeX yet; for other projects it might be similar + - [Manuel] Do we know download numbers for PDFs? I know it's possible because we are using Plausible events on Read the Docs, but I don't know how to do it. [Here is the code](https://github.com/readthedocs/website/blob/a8af8dedf1fa988f2f35002eea88cfb84c79419f/src/js/site.js#L136) we are using in case we want to do something similar or research a little more +- [Manuel] I saw a closed issue about enabling translations of code blocks. Does anyone here have experience translating code blocks? + - Best practice seems to be translating comments and string literals, but not class/variable names. But if the translator isn't a Python developer, it's hard to follow this. Sometimes the translated code doesn't work. + - [Melissa] A lot depends on the tooling and how much context you get. Do translators see the whole code block? [Manuel] Yes, one message contains the whole code. + - [Petr] Should we mark the messages and allow translation teams to turn them off? + - [Manuel] I'll research more about the discussion on GitHub and come back + +- [Daniele] I'll be doing a docs workshop @ DjangoCon US. Will anyone here be at that conference? (No ☹) + +- [Ryan] A while ago we talked about improving docs about callables in JSON docs. There's a PR waiting to be merged. [python/cpython#123394](https://github.com/python/cpython/pull/123394) + - [Petr] Will merge tomorrow + +- [Hugo] Matt Layman found that the builtin docs aren't good for beginners & built [a more approachable version](https://www.mattlayman.com/blog/2024/layman-guide-python-built-in-functions/) + - [Trey] I also have [a version](https://pym.dev/built-in-functions-in-python/) that leaves things out, built for teaching. It would be nice to have some version of this in the docs. And another [cheatsheet](https://pym.dev/string-methods/). + - [Petr] [Here's mine](https://github.com/pyvec/cheatsheets/blob/master/strings/strings-en.pdf) (the translation isn't great) + - [Trey] There are dense parts of the docs that people land on. What's the consensus for updating that? What should we do with string methods, for example? Would a PR be welcome? + - [Daniele] I think Matt's instinct is right. If you want a 12-year-old to understand what a "pivot" is, you wouldn't send them to the reference dictionary for a precise definition, history of the word, etc. They want a definition, but a simplified one. Perhaps they need a cheatsheet. + - [Trey] I could help start docs for teaching Python. + - [Hugo] Where should this go structure-wise? [Daniele] Reference. It could be next to the full reference docs. It should be linked to the full reference. + - [Melissa] Matplotlib has cheatsheets, but also has ["handouts"](https://matplotlib.org/cheatsheets/_images/handout-beginner.png), which can be seen as one big notebook + +## Follow-ups from previous meeting(s) + +*[Monthly reports archive](https://docs-community.readthedocs.io/en/latest/monthly-meeting/index.html)* + +## Next meeting + +The docs team generally meets on the first Tuesday of every month around 19:00-ish UTC. + +We have a recurring Google Calendar event for the meeting. +Let Mariatta know your email address and she can invite you. diff --git a/docs/monthly-meeting/index.rst b/docs/monthly-meeting/index.rst index 149c550..55546d0 100644 --- a/docs/monthly-meeting/index.rst +++ b/docs/monthly-meeting/index.rst @@ -24,3 +24,4 @@ Monthly reports in chronological order. Jun 2024 <2024-06.md> Jul 2024 <2024-07.md> Aug 2024 <2024-08.md> + Sep 2024 <2024-09.md> From 70681e3698d5c368fc0dc0013e1f4b01931ba8bd Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Thu, 12 Sep 2024 18:17:03 +0300 Subject: [PATCH 2/2] Ignore GitHub anchors when checking links --- docs/conf.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 8551005..b5f741b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -52,10 +52,11 @@ # A list of patterns to ignore when checking for broken links linkcheck_ignore = [ + # The crawler gets "Anchor not found" + r"https://github.com.+?#.*", + r"https://hackmd\.io/[^?]+\?[^#]+#.+", # RTD preview builds: r"https://[a-zA-Z0-9.-]+\.org\.readthedocs\.build/[a-zA-Z0-9.-]+/[a-zA-Z0-9.-]+/", # Deleted Plausible page: r"https://plausible\.io/share/hugovk-cpython\.readthedocs\.io\?auth=XDF9fK3EB2dEHCr4sC9hn", - # HackMD anchors: - r"https://hackmd\.io/[^?]+\?[^#]+#.+", ]