diff --git a/docs/monthly-meeting/2023-11.md b/docs/monthly-meeting/2023-11.md index d0d1246..b0d477e 100644 --- a/docs/monthly-meeting/2023-11.md +++ b/docs/monthly-meeting/2023-11.md @@ -49,7 +49,7 @@ Please take a second to read through it! - Next stream: [youtube.com/live/vHn4YqzYlPo](https://youtube.com/live/vHn4YqzYlPo) - [A free REPL for learning](https://tabatkins.github.io/railroad-diagrams/generator.html) -- [Ege] Looking for help on [python-docs-bootstrapper](https://github.com/egeakman/python-docs-bootstrapper/issues/8) +- [Ege] Looking for help on [python-docs-bootstrapper](https://github.com/python-docs-translations/python-docs-bootstrapper/issues/8) - Need help with: - packaging (done thanks to Hugo) diff --git a/docs/monthly-meeting/2025-02.md b/docs/monthly-meeting/2025-02.md new file mode 100644 index 0000000..69f0cdb --- /dev/null +++ b/docs/monthly-meeting/2025-02.md @@ -0,0 +1,189 @@ +# Documentation Community Team Meeting (February 2025) + +- **Date:** 2025-02-04 +- **Time:** [20:00 UTC](https://arewemeetingyet.com/UTC/2024-11-05/20:00/Docs20Meeting) +- **This HackMD:** +- [**Discourse thread**](https://discuss.python.org/t/documentation-community-meeting-tuesday-4th-february-2025/78750) + (for February) +- [**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:** + - We are using Discord this time: + + - 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]_) + +- Carol Willing / `@willingc` +- Petr Viktorin / `@encukou` +- Daniele +- Hugo van Kemenade / `@hugovk` +- Joe Kaufeld / `@itsthejoker` +- Keith +- Maciek Olko / `@m-aciek` +- Adam Turner / `@AA-Turner` +- Jeff Jacobson +- Blaise Pabon +- Stan / `@StanFromIreland` + +## Introductions + +> If there are any new people, we should do a round of introductions. + +Introductions were made. + +## Reports and celebrations + +> 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. + +> This is a place to make announcements (without a need for discussion). This is also a +> great place to give shout-outs to contributors! We'll read through these at the +> beginning of the meeting. + +- `python-docs-theme` 2025.2 was released today. +- We have narrowed supported Sphinx versions to only the latest; Sphinx 8.1. + [cpython/python#125722](https://github.com/python/cpython/issues/125722) +- We have revived efforts to generate Open Graph Protocol images ('social card + previews') + [python/docsbuild-scripts#147](https://github.com/python/docsbuild-scripts/issues/147) +- Sphinx 8.2 (upcoming) will support a `:py:deco:` cross-reference role. Thanks to + Erlend Aasland and Alex Waygood for discussion + [sphinx-doc/sphinx#13105](https://github.com/sphinx-doc/sphinx/issues/13105). +- Translation progress since 14 December 2024: + - zh-cn: 79.46% -> 80.64% + - es: 62.38% -> 63.28% + - pt-br: 53.79% -> 58.24% + - zh-tw: 36.62% -> 37.00% + - pl: 8.24% -> 9.44% + - gr: 4.62% -> 4.83% + - (please note that as of now completion tracking bases on paragraphs number, not + [words](https://github.com/izimobil/polib/pull/166) number, and may not express the + translation effort precisely) + - [source](https://github.com/m-aciek/pydocs-translation-dashboard/compare/f015a5c401118514c12ae4c75328a201a46171c5...gh-pages) + +## Discussion + +- The [Python Wiki](https://wiki.python.org/moin/Documentation) has a great deal of + information, but much of it is badly outdated. For documentation-related pages, + perhaps we ought remove these and redirect readers to d.p.o? + - [Hugo] This came up recently. Marc-André was keen on keeping the wiki around. See + + - [Carol] Would love to see the wiki go away completely. First, we should go through + the d.p.o docs and remove references to the wiki. There's a lot of out-of-date + stuff, and it's very confusing. + - [Hugo] There are 22 instances of `wiki.python` in the docs. + - People might be against deleting stuff. + - Wikis are useful when they're kept outdated. This one isn't. + - [Daniele] We have the same problem at work; people don't want to throw it away but + it's mostly garbage and no one wants to go through it and make it better. + - [Joe] Would it be useful to add a banner that explicitly says it's unmaintained? + - [Adam] There are some pages that are actively maintained. We can change it, but it's + onerous to make edits. Don't know how to get history or get the content. + - [Carol] I still think I have wiki access. After we get the links out of d.p.o, maybe + we can go through the wiki, search for CPython and replace the info with links to + docs. It's a heavy lift to get rid of it. +- There has been a long discussion on syntax and style for describing Python types in + documentation, primarily taking place in the comments of a merged PR(!) in the Sphinx + repository [sphinx-doc/sphinx#13242](https://github.com/sphinx-doc/sphinx/pull/13242). + Do we wish to take a view here? + - [Adam] In our docs, we can mark up types as static annotations in Python, or + describe them in prose. Which do we want to standardize on? This was already + discussed; are there any strong opinions we could take to the EB? + - [Carol] Adam will go to the next EB meeting and hopefully it'll get resolved. +- Request for comment: how best to present abstract methods and classes? See + [sphinx-doc/sphinx#13271](https://github.com/sphinx-doc/sphinx/pull/13271). Options: + - _`abstractmethod`_` write()` + - _`abstract method`_` write()` + - _`abstract`_` write()` + * [Petr] Would it be possible to link that word to the glossary? (yes, we could) +- Request for comment: how tightly should we draw the distinction between 'async', + 'awaitable', and 'coroutine' callables? Note that Python's documentation currently + uses the latter two forms, but Sphinx only (currently) supports the former. + - [`:async:` option](https://www.sphinx-doc.org/en/master/usage/domains/python.html#directive-option-py-function-async) + (Sphinx) + - coro example: + [`asyncio.sleep`](https://docs.python.org/3/library/asyncio-task.html#asyncio.sleep) + - awaitable example: + [`asyncio.gather`](https://docs.python.org/3/library/asyncio-task.html#asyncio.gather) + * [Petr] the distinction is confusing; ideally they should be made equivalent. But as + long as they're different, the docs should be precise + +### Python Project Documentation + +_Relating to `docs.python.org`, `peps.python.org`, `devguide.python.org`, etc._ + +- [bswck] Track upstream->downstream translation block update alerts + + - Not discussed. + +- [Hugo] The availability directives are like: + `.. availability:: Linux >= 2.6.27 with glibc >= 2.8`. Should we automatically replace + ">=" with "≥", or rewrite as "version 2.8 or later" per Google, Microsoft and Apple + style guides? + [python/cpython#129597 (comment)](https://github.com/python/cpython/pull/129597#discussion_r1939080570) + + - [Petr] I'd keep the directives compact; they're not prose + - [Joe] I'd use the single symbol + - [Joe] The Unicode symbol was introduced in 1993, hopefully it renders well on near + anything + - [Petr] If there's an issue with Unicode in some of the backends, we should fix that + +- [Hugo] Links back to homepage: + [python/python-docs-theme#217](https://github.com/python/python-docs-theme/issues/217) + + - [Adam] PEPs have a link to both python.org and peps.python.org. It's probably best + to have both links. If I'd have to choose, I'd have the icon either unlinked or go + to `docs.`. + - [Petr] I'd rather have the link go to docs.python.org. It'd be more useful to folks + who are visiting for the first time, and then have the docs homepage itself have a + link to the standard python.org. + +- [Maciek] Moving into the inside of the Python GitHub organization + + - Python Docs Translation Dashboard repository? + - Transifex automation repository? + - or should we add a new organization for the around-translations-efforts? + - [Petr] I recommend a new organization, where you're an admin and can set it up + however you want + - [Repo policy](https://devguide.python.org/developer-workflow/development-cycle/#organization-repository-policy) + - [Adam] This could live under `python`, the question is if it's a good idea. It might + make it easier to maintain. + - [Adam] For the dashboard, eventually we could move it to a folder in the + docsbuild-scripts repo. + - [Carol] I like both options, but note that we can always move repos from a + translations organization to `python` + - [Hugo] We might want to add the dashboard directly to the devguide. Maybe by having + it generate a JSON file that devguide consumes? + - [maciek] An organization is good for discoverability, and for shared maintenance in + case the original maintainer steps down. + - [Adam] Could we create a python-translations organization right now? + ([yes](https://github.com/python-docs-translations)) + - [Adam] Is the devguide the best place for the dashboard? Maybe we should have the + dashboard on docs.python.org somewhere + +- [Maciek] Is displaying number of Sphinx build warnings in scope of Python Docs + Translation Dashboard + [dashboard#45](https://github.com/python-docs-translations/dashboard/pull/45) + - [Hugo] Would it be useful to you as a translator? (yes) + - [Adam] We don't use nitpicky mode currently. Instinctively, going to the level of + sphinx warnings is a bit much. + - [Maciek] It could be a motivation for potential contributors. + +## Next meeting + +The docs team generally meets on the first Tuesday of every month around 20: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 59f6ef3..5c61c53 100644 --- a/docs/monthly-meeting/index.rst +++ b/docs/monthly-meeting/index.rst @@ -29,3 +29,4 @@ Monthly reports in chronological order. Nov 2024 <2024-11.md> Dec 2024 <2024-12.md> Jan 2025 <2025-01.md> + Feb 2025 <2025-02.md>