8000 Add September 2024 meeting notes (#130) · python/docs-community@04ed295 · GitHub
[go: up one dir, main page]

Skip to content

Commit 04ed295

Browse files
authored
Add September 2024 meeting notes (#130)
1 parent 3c1973e commit 04ed295

File tree

3 files changed

+93
-2
lines changed

3 files changed

+93
-2
lines changed

docs/conf.py

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -52,10 +52,11 @@
5252

5353
# A list of patterns to ignore when checking for broken links
5454
linkcheck_ignore = [
55+
# The crawler gets "Anchor not found"
56+
r"https://github.com.+?#.*",
57+
r"https://hackmd\.io/[^?]+\?[^#]+#.+",
5558
# RTD preview builds:
5659
r"https://[a-zA-Z0-9.-]+\.org\.readthedocs\.build/[a-zA-Z0-9.-]+/[a-zA-Z0-9.-]+/",
5760
# Deleted Plausible page:
5861
r"https://plausible\.io/share/hugovk-cpython\.readthedocs\.io\?auth=XDF9fK3EB2dEHCr4sC9hn",
59-
# HackMD anchors:
60-
r"https://hackmd\.io/[^?]+\?[^#]+#.+",
6162
]

docs/monthly-meeting/2024-09.md

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Documentation Community Team Meeting (September 2024)
2+
3+
- **Date:** 2024-09-03
4+
- **Time:** [19:00 UTC](https://arewemeetingyet.com/UTC/2024-09-03/19:00/Docs%20Meeting)
5+
- **This HackMD:** <https://hackmd.io/@encukou/pydocswg1>
6+
- [**Discourse thread**](https://discuss.python.org/t/documentation-community-meeting-tuesday-3rd-september-2024/62175) (for September)
7+
- [**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))
8+
- **Calendar event:** (send your e-mail to Mariatta for an invitation)
9+
- **How to participate:**
10+
- Go to [Google Meet](https://meet.google.com/dii-qrzf-wkw) and ask to be let in.
11+
- To edit notes, click the “pencil” or “split view” button on the [HackMD document](https://hackmd.io/@encukou/pydocswg1).
12+
You need to log in (e.g. with a GitHub account).
13+
14+
By participating in this meeting, you are agreeing to abide by and uphold the [PSF Code of Conduct](https://www.python.org/psf/codeofconduct/).
15+
Please take a second to read through it!
16+
17+
## Roll call
18+
19+
(Name / `@GitHubUsername` *[/ Discord, if different]*)
20+
21+
- Daniele Procida / @EvilDMP
22+
- Hugo van Kemenade / @hugovk
23+
- Trey / @treyhunner
24+
- Manuel / `@humitos`
25+
- Melissa / @melissawm
26+
- Petr Viktorin / @encukou
27+
- Ryan / `@ryan-duve`
28+
29+
## Discussion
30+
31+
- [Hugo]
32+
- As a RM, logged into the docs server, and fixed a bunch of stopped jobs
33+
- It would be nice to have 2 cron jobs -- one for HTML (fast), one for PDFs (slow)
34+
- 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
35+
- Separately, we want to move HTML to Read the Docs, while keeping the ability to build them separately
36+
37+- Dropping PDF builds - should we drop one of the formats (A4/letter)?
38+
- [Danilel] PDF is used for e-mail from sales, and for air-gapped environments.
39+
- [Melissa?] If drop both, would need alternative, such as single page HTML [Petr?] And give some love to the print styles
40+
- [Trey] Is HTML faster to build? [Hugo] Yes, about 3 mins for HTML compared to 30 min to 2 hours for full set:
41+
| Start | Language/version | Build |
42+
| :--------------: | :--------------: |------: |
43+
| 2024-09-02 23:53 | zh-tw/3.13 | 1h 44m |
44+
| 2024-09-03 01:39 | zh-cn/3.13 | 1h 32m |
45+
| 2024-09-03 03:13 | uk/3.13 | 3m |
46+
| 2024-09-03 03:17 | tr/3.13 | 1h 45m |
47+
| 2024-09-03 05:04 | pt-br/3.13 | 40m |
48+
| 2024-09-03 05:45 | pl/3.13 | 33m |
49+
| 2024-09-03 06:20 | ko/3.13 | 54m |
50+
| 2024-09-03 07:16 | ja/3.13 | 1h 23m |
51+
| 2024-09-03 08:40 | it/3.13 | 32m |
52+
| 2024-09-03 09:13 | id/3.13 | 42m |
53+
| 2024-09-03 10:25 | es/3.13 | 1h 59m |
54+
| 2024-09-03 12:25 | en/3.13 | 32m |
55+
- [Manuel] What's the frequency? [Hugo] 24 hours or more
56+
- [Manuel] Can we build PDFs less often? People who download them probably read them offline.
57+
- [Melissa] What about rinohtype? [brechtm/rinohtype](https://github.com/brechtm/rinohtype) <https://www.mos6581.org/rinohtype/master/> [Daniele] It's as slow as LaTeX; the typesetting quality should be comparable.
58+
- [Melissa] For NumPy/SciPy there's nothing that can replace LaTeX yet; for other projects it might be similar
59+
- [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
60+
- [Manuel] I saw a closed issue about enabling translations of code blocks. Does anyone here have experience translating code blocks?
61+
- 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.
62+
- [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.
63+
- [Petr] Should we mark the messages and allow translation teams to turn them off?
64+
- [Manuel] I'll research more about the discussion on GitHub and come back
65+
66+
- [Daniele] I'll be doing a docs workshop @ DjangoCon US. Will anyone here be at that conference? (No ☹)
67+
68+
- [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)
69+
- [Petr] Will merge tomorrow
70+
71+
- [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/)
72+
- [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/).
73+
- [Petr] [Here's mine](https://github.com/pyvec/cheatsheets/blob/master/strings/strings-en.pdf) (the translation isn't great)
74+
- [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?
75+
- [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.
76+
- [Trey] I could help start docs for teaching Python.
77+
- [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.
78+
- [Melissa] Matplotlib has cheatsheets, but also has ["handouts"](https://matplotlib.org/cheatsheets/_images/handout-beginner.png), which can be seen as one big notebook
79+
80+
## Follow-ups from previous meeting(s)
81+
82+
*[Monthly reports archive](https://docs-community.readthedocs.io/en/latest/monthly-meeting/index.html)*
83+
84+
## Next meeting
85+
86+
The docs team generally meets on the first Tuesday of every month around 19:00-ish UTC.
87+
88+
We have a recurring Google Calendar event for the meeting.
89+
Let Mariatta know your email address and she can invite you.

docs/monthly-meeting/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,3 +24,4 @@ Monthly reports in chronological order.
2424
Jun 2024 <2024-06.md>
2525
Jul 2024 <2024-07.md>
2626
Aug 2024 <2024-08.md>
27+
Sep 2024 <2024-09.md>

0 commit comments

Comments
 (0)
0