Merge branch 'main' into september

python · Sep 22, 2023 · 673d1e0 · 673d1e0
2 parents 607e499 + 8bd026e
commit 673d1e0
Show file tree

Hide file tree

Showing 24 changed files with 85 additions and 57 deletions.
diff --git a/.github/workflows/lint.yaml b/.github/workflows/lint.yaml
@@ -0,0 +1,17 @@
+name: Lint
+
+on: [push, pull_request, workflow_dispatch]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.x"
+      - uses: pre-commit/[email protected]
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -0,0 +1,19 @@
+repos:
+  - repo: https://github.com/psf/black-pre-commit-mirror
+    rev: 23.9.1
+    hooks:
+      - id: black
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+
+  - repo: https://github.com/sphinx-contrib/sphinx-lint
+    rev: v0.6.8
+    hooks:
+      - id: sphinx-lint
diff --git a/README.md b/README.md
@@ -36,4 +36,3 @@ For example, to find out more about us and what we do, [read the docs](https://d
    ```console
    sphinx-autobuild --open-browser docs docs/_build
    ```
-
diff --git a/docs/Makefile b/docs/Makefile
@@ -17,4 +17,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/community/community-guide.md b/docs/community/community-guide.md
@@ -25,4 +25,3 @@ In this respect, we are using:
 questions, or just as a place where we can inspire each other.
 
 ## How can I help?
-
diff --git a/docs/community/skills.md b/docs/community/skills.md
@@ -2,7 +2,7 @@
 
 ## Where to start?
 
-The short answer to this question is: follow your interests :-) 
+The short answer to this question is: follow your interests :-)
 
 ## A few general ways to help out
 
@@ -25,5 +25,3 @@ you scope the work you'd like to do, and to set expectations.
 ## Resources for Learning
 
 In this section, we gather some introductory materials for learning the aforementioned tools.
-
-
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,5 +1,5 @@
 ==============================
-Python Documentation Community 
+Python Documentation Community
 ==============================
 
 The following pages contain information about the documentation workgroup,

diff --git a/docs/monthly-meeting/2022-02.md b/docs/monthly-meeting/2022-02.md
@@ -22,14 +22,14 @@ On the first meeting, let's use this slot for an introduction!
 ## Roll call:
 
 - [name] / affiliation / github username
-- [Pradyun] / :shrug: / @pradyunsg 
+- [Pradyun] / :shrug: / @pradyunsg
 - [willingc] / Core Dev / willingc
 - [Ned] / edX, Open edX, Boston Python, Coverage.py / @nedbat
 - James
 - [Petr] / Core Dev & SC / @encukou
 - Mariatta / Core Dev / @mariatta
 - [CAM] @CAM-Gerlach PEP Editor / NASA Scientist
-- Paul 
+- Paul
 
 ## Reports and celebrations
 
@@ -225,7 +225,7 @@ The group's docs are incomplete. Should we fill in the blanks? Scrap some pages
 
 ### Documentation guidance
 
-> Having a clear and opinionated style guide can enable more contributions.  It will clarify expectations, making it easier to create pull requests that will get accepted.  It will remove individual ownership of pages, which creates roadblocks to merging. [Ned] 
+> Having a clear and opinionated style guide can enable more contributions.  It will clarify expectations, making it easier to create pull requests that will get accepted.  It will remove individual ownership of pages, which creates roadblocks to merging. [Ned]
 
 The style guide could cover questions like:
 

diff --git a/docs/monthly-meeting/2022-03.md b/docs/monthly-meeting/2022-03.md
@@ -63,7 +63,7 @@ Please take a second to read through it!
 
 ### Structuring Docs, Devguide, and PEPs
 
-* Some PEPs are turning into long-lived documentations. 
+* Some PEPs are turning into long-lived documentations.
     * Packaging PEPs used to be, moving to packaging.python.org
     * typing is moving into a similar situation.
 * `__future__` page in Python docs is also a list of PEP references.
@@ -123,4 +123,3 @@ Next meeting: April 4th, 22:00 UTC
 
 We have a Google Calendar event for the next meeting, set to recur on the first Monday of each month.
 Let Mariatta know your email address and she can invite you to the event.
-
diff --git a/docs/monthly-meeting/2022-04.md b/docs/monthly-meeting/2022-04.md
@@ -70,7 +70,7 @@ Devguide PR: https://github.com/python/devguide/pull/814
 
 ### Structuring Docs, Devguide, and PEPs
 
-* Some PEPs are turning into long-lived documentations. 
+* Some PEPs are turning into long-lived documentations.
     * Packaging PEPs used to be, moving to packaging.python.org
     * typing is moving into a similar situation.
 * `__future__` page in Python docs is also a list of PEP references.
@@ -148,7 +148,7 @@ The group's docs are incomplete. Should we fill in the blanks? Scrap some pages
 
 ### Documentation guidance
 
-> Having a clear and opinionated style guide can enable more contributions.  It will clarify expectations, making it easier to create pull requests that will get accepted.  It will remove individual ownership of pages, which creates roadblocks to merging. [name=Ned] 
+> Having a clear and opinionated style guide can enable more contributions.  It will clarify expectations, making it easier to create pull requests that will get accepted.  It will remove individual ownership of pages, which creates roadblocks to merging. [name=Ned]
 
 The style guide could cover questions like:
 
@@ -171,4 +171,3 @@ Plan is to meet First Monday of the month.
 
 We have a Google Calendar event for the next meeting, set to recur on the first Monday of each month.
 Let Mariatta know your email address and she can invite you to the event.
-
diff --git a/docs/monthly-meeting/2022-06.md b/docs/monthly-meeting/2022-06.md
@@ -61,7 +61,7 @@ Needs discussion, please open issue on core-workflow repo.
 > If we rename the WG to an Editorial Board, we should clarify the interpretation of the name.
 >
 > A quarterly meeting for the WG seems like the right cadence.
-> 
+>
 > Editorial Board is the agreed name. Wikipedia has a good definition which aligns with our meaning.
 
 Status: There are currently no meetings for the editorial board.
@@ -139,7 +139,7 @@ Daniele: We should consider not only consensus on adopting the framework, but al
 
 Ned: What's a workshop?
 
-Daniele: Two 2-hour interactive workshops: theory, interactive exercises, 
+Daniele: Two 2-hour interactive workshops: theory, interactive exercises,
 Normally it's in-person.
 
 Ned: Who'd participate?

diff --git a/docs/monthly-meeting/2022-07.md b/docs/monthly-meeting/2022-07.md
@@ -47,7 +47,7 @@ Please take a second to read through it!
 
 > 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.
 
-* Diátaxis workshop has a date & signup form: 
+* Diátaxis workshop has a date & signup form:
   - [Announcement post](https://discuss.python.org/t/17075)
   - [Registration form](https://forms.gle/xQSZJ2Yf4Jjd27wf6)
   - Dates: 16 Aug (pt. 1) & 18 Aug (pt. 2), both 4pm-6pm UTC
@@ -99,7 +99,7 @@ None
     * explicit boxes/directives
     * naming conventions for sections
     * naming conventions for anchors
-      * (i.e. ``.. _<module>-guide:``; ``.. _<module>-reference:``) 
+      * (i.e. ``.. _<module>-guide:``; ``.. _<module>-reference:``)
       * global summary page/table
   * bunch-of-functions modules vs ~frameworks
   * page structure

diff --git a/docs/monthly-meeting/2022-08.md b/docs/monthly-meeting/2022-08.md
@@ -60,17 +60,17 @@ Please take a second to read through it!
     -  Ned: Why do we need a PEP?
     -  Daniele: when it comes to adopting diataxis, but it's a decision that should be taken after the workshops. After the workshops people will have clearer idea and implications of what it will mean for the docs. If there is a strong consensus, that's when we should work that decision into a PEP. It needs to be really understood by the people making small changes. The PEP of styling is the same.
     -  Petr: Diataxis is more about direction, should be more of a Discourse discussion other than a PEP
-    -  Ned: How much decision-making we need ahead of time before starting working with Diataxis.  
+    -  Ned: How much decision-making we need ahead of time before starting working with Diataxis.
     -  Petr: the purpose of the PEP is to make sure you consider everything about the problem, make sure everybody that should be heard is heard, make sure everything is documented. If you can get to that goal some other way, then we don't need a PEP.
     -  Daniele: it's like a deciding: Are we going to climb up that mountain? Which mountain? Once we decided on which mountain, we better make sure we're equipped for that, we don't need all the plans, but still need agreement.
     -  Ned: What are we writing in this PEP? It can be just one paragraph, or 10 pages.
-    -  Petr: There is a PEP template ([PEP 12](https://peps.python.org/pep-0012/)). 
+    -  Petr: There is a PEP template ([PEP 12](https://peps.python.org/pep-0012/)).
     -  Ned: How is a PEP ... ?
     -  Daniele: We need to have a clear picture of where we want to go.
     -  Petr: let's leave this for after the workshop
     -  Pradyun: PEP is our tool for consensus building.
-    -  Hugo: With [PEP 676](https://peps.python.org/pep-0676/): work was done ahead before the PEP, and we didn't really know who was going to make the decision of it, and after the PEP there was more clarity of who makes the decision. 
-    -  CAM: a PEP can be design docs or detailed plan, but can also be a rationale. 
+    -  Hugo: With [PEP 676](https://peps.python.org/pep-0676/): work was done ahead before the PEP, and we didn't really know who was going to make the decision of it, and after the PEP there was more clarity of who makes the decision.
+    -  CAM: a PEP can be design docs or detailed plan, but can also be a rationale.
     -  Pradyun: We don't want to put in process that makes it more difficult for people to contribute.
 
 ## Next meeting

diff --git a/docs/monthly-meeting/2022-10.md b/docs/monthly-meeting/2022-10.md
@@ -63,8 +63,8 @@ If enabled, what should it be aliased to?
 * [python/pythondotorg#1691](https://github.com/python/pythondotorg/issues/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. 
+    * 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

diff --git a/docs/monthly-meeting/2022-11.md b/docs/monthly-meeting/2022-11.md
@@ -28,7 +28,7 @@ Please take a second to read through it!
 
 > 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.
 
-- Mariatta: Python BR keynote 
+- Mariatta: Python BR keynote
 - Jim DeLaHunt: pass
 - Ezio: devguide, [CSV with status of Python branches](https://github.com/python/devguide/pull/884), [OpenGraph metadata for devguide et al.](https://github.com/python/devguide/pull/953), catching up after a busy month
 - Erlend: getting help from Cam on two huge PRs on SQLite docs
@@ -44,8 +44,8 @@ Please take a second to read through it!
 
 
 - Infrastructure & detecting/avoiding broken links
-    - how to get visibility of docs traffic and broken url hits? 
-        - First step: ask [#PSF category on Discourse](https://discuss.python.org/c/python-software-foundation/9). 
+    - how to get visibility of docs traffic and broken url hits?
+        - First step: ask [#PSF category on Discourse](https://discuss.python.org/c/python-software-foundation/9).
         - Done, see [Discourse thread](https://discuss.python.org/t/data-on-requests-for-missing-urls-in-docs-python-org-etc/20841) —JDLH
         - Probably Ee [@EWDurbin](https://discuss.python.org/u/ewdurbin/summary) oversees this, but better not to start there, Ee is busy.
     - need help from Ee about docs preview on Netlify

diff --git a/docs/monthly-meeting/2023-02.md b/docs/monthly-meeting/2023-02.md
@@ -1,7 +1,7 @@
 # Documentation Community Team Meeting (February 2023)
 
-- **Date:** 2023-02-06 
-- **Time:** [20:00 UTC](https://arewemeetingyet.com/UTC/2023-01-09/20:00/Docs%20Meeting) 
+- **Date:** 2023-02-06
+- **Time:** [20:00 UTC](https://arewemeetingyet.com/UTC/2023-01-09/20:00/Docs%20Meeting)
 - **This HackMD:** https://hackmd.io/@encukou/pydocswg1
 - [**Discourse thread**](https://discuss.python.org/t/documentation-community-meeting-february-6-2023/23320) (for February)
 - [**January meeting's report**](https://docs-community.readthedocs.io/en/latest/monthly-meeting/2023-01.html)
@@ -27,7 +27,6 @@ Please take a second to read through it!
 ## 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.
 
@@ -68,7 +67,7 @@ Please take a second to read through it!
 
 - [python/devguide#1020](https://github.com/python/devguide/issues/1020): Function signatures in docs (positional-only markers, defaults, `[]` syntax)
   - How discoverable is the `[]` syntax to today's devs?
- 
+
 - The docs mailing list ([email protected])
     - This is linked from docs.python.org from "report a bug" section https://docs.python.org/3/bugs.html#documentation-bugs
     - [python/devguide#1025](https://github.com/python/devguide/pull/1025)

diff --git a/docs/monthly-meeting/2023-04.md b/docs/monthly-meeting/2023-04.md
@@ -1,7 +1,7 @@
 # Documentation Community Team Meeting (April 2023)
 
 - **Date:** 2023-04-03
-- **Time:** [19:00 UTC](https://arewemeetingyet.com/UTC/2023-03-06/19:00/Docs%20Meeting) 
+- **Time:** [19:00 UTC](https://arewemeetingyet.com/UTC/2023-03-06/19:00/Docs%20Meeting)
 - **This HackMD:** https://hackmd.io/@encukou/pydocswg1
 - [**Discourse thread**](https://discuss.python.org/t/25337) (for April)
 - [**Meeting reports**](https://docs-community.readthedocs.io/en/latest/monthly-meeting/index.html) (the latest one might be an [**unmerged PR**](https://github.com/python/docs-community/pulls))

diff --git a/docs/monthly-meeting/2023-05.md b/docs/monthly-meeting/2023-05.md
@@ -1,7 +1,7 @@
 # Documentation Community Team Meeting (May 2023)
 
 - **Date:** 2023-05-01
-- **Time:** [19:00 UTC](https://arewemeetingyet.com/UTC/2023-05-01/19:00/Docs%20Meeting) 
+- **Time:** [19:00 UTC](https://arewemeetingyet.com/UTC/2023-05-01/19:00/Docs%20Meeting)
 - **This HackMD:** https://hackmd.io/@encukou/pydocswg1
 - [**Discourse thread**](https://discuss.python.org/t/26182) (for May)
 - [**Meeting reports**](https://docs-community.readthedocs.io/en/latest/monthly-meeting/index.html) (the latest one might be an [**unmerged PR**](https://github.com/python/docs-community/pulls))
@@ -88,7 +88,7 @@ Congrats Ned for the [keynote at PyCon US 2023](https://us.pycon.org/2023/about/
 * [Ned] Best entry point to working on docs, for people newly interested in helping?
     - we need clear onboarding
     - do we have style guide?
-    - Cristian: In the python-docs-es team we have [a page inside the docs](https://python-docs-es.readthedocs.io/es/3.11/CONTRIBUTING.html) (docs-ception) that teaches the whole process 
+    - Cristian: In the python-docs-es team we have [a page inside the docs](https://python-docs-es.readthedocs.io/es/3.11/CONTRIBUTING.html) (docs-ception) that teaches the whole process
     - how do we write such docs?
         - HackMD or Google Docs
     - [Python Docs Community web page](https://docs-community.readthedocs.io/en/latest/)

diff --git a/docs/monthly-meeting/2023-06.md b/docs/monthly-meeting/2023-06.md
@@ -1,7 +1,7 @@
 # Documentation Community Team Meeting (June 2023)
 
 - **Date:** 2023-06-05
-- **Time:** [19:00 UTC](https://arewemeetingyet.com/UTC/2023-06-05/19:00/Docs%20Meeting) 
+- **Time:** [19:00 UTC](https://arewemeetingyet.com/UTC/2023-06-05/19:00/Docs%20Meeting)
 - **This HackMD:** https://hackmd.io/@encukou/pydocswg1
 - [**Discourse thread**](https://discuss.python.org/t/27334) (for June)
 - [**Meeting reports**](https://docs-community.readthedocs.io/en/latest/monthly-meeting/index.html) (the latest one might be an [**unmerged PR**](https://github.com/python/docs-community/pulls))

diff --git a/docs/monthly-meeting/2023-07.md b/docs/monthly-meeting/2023-07.md
@@ -1,7 +1,7 @@
 # Documentation Community Team Meeting (July 2023)
 
 - **Date:** 2023-07-03
-- **Time:** [19:00 UTC](https://arewemeetingyet.com/UTC/2023-07-03/19:00/Docs%20Meeting) 
+- **Time:** [19:00 UTC](https://arewemeetingyet.com/UTC/2023-07-03/19:00/Docs%20Meeting)
 - **This HackMD:** [https://hackmd.io/@encukou/pydocswg1](https://hackmd.io/@encukou/pydocswg1)
 - [**Discourse thread**](https://discuss.python.org/t/28736) (for July)
 - [**Meeting reports**](https://docs-community.readthedocs.io/en/latest/monthly-meeting/index.html) (the latest one might be an [**unmerged PR**](https://github.com/python/docs-community/pulls))

diff --git a/docs/monthly-meeting/2023-08.md b/docs/monthly-meeting/2023-08.md
@@ -1,7 +1,7 @@
 # Documentation Community Team Meeting (August 2023)
 
 - **Date:** 2023-08-01
-- **Time:** [19:00 UTC](https://arewemeetingyet.com/UTC/2023-08-01/19:00/Docs%20Meeting) 
+- **Time:** [19:00 UTC](https://arewemeetingyet.com/UTC/2023-08-01/19:00/Docs%20Meeting)
 - **This HackMD:** https://hackmd.io/@encukou/pydocswg1
 - [**Discourse thread**](https://discuss.python.org/t/30549) (for August)
 - [**Meeting reports**](https://docs-community.readthedocs.io/en/latest/monthly-meeting/index.html) (the latest one might be an [**unmerged PR**](https://github.com/python/docs-community/pulls))
@@ -17,7 +17,7 @@ Please take a second to read through it!
 ## Roll call
 
 (Name / `@GitHubUsername` / Discord if different)
-- Hugo van Kemenade  / `@hugovk` 
+- Hugo van Kemenade  / `@hugovk`
 - Daniele Procida
 - Manuel Kaufmann / `@humitos`
 - Ryan Duve / `@ryan-duve`
@@ -29,7 +29,7 @@ Please take a second to read through it!
 
 ## Reports and celebrations
 
-- [PR to keep "translated" attribute on translated nodes](https://github.com/sphinx-doc/sphinx/pull/11502) landed and released! :tada: 
+- [PR to keep "translated" attribute on translated nodes](https://github.com/sphinx-doc/sphinx/pull/11502) landed and released! :tada:
     - https://github.com/python/docsbuild-scripts/issues/148#issuecomment-1648836409 has the details on how it's exposed!
 
 - [Hugo] CPython sprint at EuroPython: we had one room for code and another for documentation, and merged some 140 PRs in total! Thanks to Daniele for helping out and all the excellent docs advice! (Photos: https://mastodon.social/@hugovk/110792652209141428)
@@ -48,7 +48,7 @@ Please take a second to read through it!
     - Ask PSF/Ee if we want to self-host, or pay for the service (or get sponsored)
     - Let the SC look at the dashboard
 
-- [Hugo] Dark theme deploy: 3.11 RM Pablo said fine to deploy. To deploy, need to merge [python/docsbuild-scripts#161](https://github.com/python/docsbuild-scripts/pull/161) and/or pin in `requirements.txt` 
+- [Hugo] Dark theme deploy: 3.11 RM Pablo said fine to deploy. To deploy, need to merge [python/docsbuild-scripts#161](https://github.com/python/docsbuild-scripts/pull/161) and/or pin in `requirements.txt`
 
 - [CAM] Update on structured deprecation work
     - Originaly prompted by [a recent Discourse thread on soft deprecations](https://discuss.python.org/t/formalize-the-concept-of-soft-deprecation-dont-schedule-removal-in-pep-387-backwards-compatibility-policy/27957/73)
@@ -60,8 +60,8 @@ Please take a second to read through it!
         - JSON, etc. output schema
         - Worked through examples
         - Open questions and additional notes
-    - Initial implementation currently in progress; should have a final 
-    
+    - Initial implementation currently in progress; should have a final
+
 - [Daniele] On-going documentation commit approaches
     - suggest changing approach to docs PRs
       - Often a PR will make docs look *worse* -- highlight what needs to be changed

diff --git a/docs/workgroup/adding-members.rst b/docs/workgroup/adding-members.rst
@@ -7,4 +7,3 @@ them.
 
 Adding a new workgroup member
 =============================
-
diff --git a/docs/workgroup/milestones.rst b/docs/workgroup/milestones.rst
@@ -2,4 +2,4 @@
 Milestones and roadmaps
 =======================
 
-TBD
+TBD