├── .github
    ├── ISSUE_TEMPLATE
    │   ├── config.yml
    │   ├── contributors.md
    │   └── readers.md
    └── workflows
    │   └── hugo.yaml
├── README.md
├── archetypes
    ├── changelog.md
    ├── default.md
    └── updates.md
├── assets
    └── css
    │   └── extended
    │       └── custom.css
├── content
    ├── archives.md
    ├── changelog
    │   ├── 2024-07-12-function-signatures.md
    │   ├── 2024-07-18-clarify-timezone.md
    │   ├── 2024-08-28-style-guide-recs.md
    │   ├── 2024-10-14-devguide-reorg.md
    │   ├── 2024-11-11-dead-batteries-docs.md
    │   ├── 2025-03-11-pipes-or-in-sphinx-type-descriptions.md
    │   └── _index.md
    ├── search.md
    └── updates
    │   ├── 2024-01-08-editorial-board-update.md
    │   ├── 2024-02-12-editorial-board-update.md
    │   ├── 2024-03-11-editorial-board-update.md
    │   ├── 2024-04-08-editorial-board-update.md
    │   ├── 2024-06-03-editorial-board-update.md
    │   ├── 2024-08-12-editorial-board-update.md
    │   ├── 2024-09-09-editorial-board-update.md
    │   ├── 2024-10-14-editorial-board-update.md
    │   ├── 2024-11-11-editorial-board-update.md
    │   ├── 2024-12-10-editorial-board-update.md
    │   ├── 2025-01-14-editorial-board-update.md
    │   ├── 2025-02-11-editorial-board-update.md
    │   ├── 2025-03-11-editorial-board-update.md
    │   └── 2025-04-08-editorial-board-update.md
├── go.mod
├── hugo.yaml
├── layouts
    ├── _default
    │   └── single.html
    ├── changelog
    │   └── list.html
    └── partials
    │   └── members.html
└── netlify.toml


/.github/ISSUE_TEMPLATE/config.yml:
--------------------------------------------------------------------------------
1 | blank_issues_enabled: true
2 | 


--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/contributors.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | name: Improve life for doc contributors
 3 | about: Suggest something that will improve things for doc contributors
 4 | title: For contributors -- <topic>
 5 | labels: contributors
 6 | assignees: ''
 7 | 
 8 | ---
 9 | <!-- Please make sure this idea has been discussed on Discourse or GitHub first
10 |      See https://discuss.python.org or https://github.com/python/cpython/issues
11 | -->
12 | 
13 | * [ ] Link to discussion about the proposal (Discourse or GitHub): [title](link)
14 | 


--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/readers.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | name: Improve life for doc readers 
 3 | about: Suggest something that will improve things for doc readers
 4 | title: For readers -- <topic>
 5 | labels: readers
 6 | assignees: ''
 7 | 
 8 | ---
 9 | <!-- Please make sure this idea has been discussed on Discourse or GitHub first
10 |      See https://discuss.python.org or https://github.com/python/cpython/issues
11 | -->
12 | 
13 | * [ ] Link to discussion about the proposal (Discourse or GitHub): [title](link)
14 | 


--------------------------------------------------------------------------------
/.github/workflows/hugo.yaml:
--------------------------------------------------------------------------------
 1 | # Workflow for deploying the site to GitHub Pages
 2 | # Copied from: https://gohugo.io/hosting-and-deployment/hosting-on-github/
 3 | name: Deploy Hugo site to Pages
 4 | 
 5 | on:
 6 |   # Runs on pushes targeting the default branch
 7 |   push:
 8 |     branches:
 9 |       - main
10 | 
11 |   # Allows you to run this workflow manually from the Actions tab
12 |   workflow_dispatch:
13 | 
14 | # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
15 | permissions:
16 |   contents: read
17 |   pages: write
18 |   id-token: write
19 | 
20 | # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
21 | # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
22 | concurrency:
23 |   group: "pages"
24 |   cancel-in-progress: false
25 | 
26 | # Default to bash
27 | defaults:
28 |   run:
29 |     shell: bash
30 | 
31 | jobs:
32 |   # Build job
33 |   build:
34 |     runs-on: ubuntu-latest
35 |     env:
36 |       HUGO_VERSION: 0.128.0
37 |     steps:
38 |       - name: Install Hugo CLI
39 |         run: |
40 |           wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
41 |           && sudo dpkg -i ${{ runner.temp }}/hugo.deb
42 |       - name: Install Dart Sass
43 |         run: sudo snap install dart-sass
44 |       - name: Checkout
45 |         uses: actions/checkout@v4
46 |         with:
47 |           submodules: recursive
48 |           fetch-depth: 0
49 |       - name: Setup Pages
50 |         id: pages
51 |         uses: actions/configure-pages@v5
52 |       - name: Install Node.js dependencies
53 |         run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
54 |       - name: Build with Hugo
55 |         env:
56 |           HUGO_CACHEDIR: ${{ runner.temp }}/hugo_cache
57 |           HUGO_ENVIRONMENT: production
58 |           TZ: America/Los_Angeles
59 |         run: |
60 |           hugo \
61 |             --gc \
62 |             --minify \
63 |             --baseURL "${{ steps.pages.outputs.base_url }}/"
64 |       - name: Upload artifact
65 |         uses: actions/upload-pages-artifact@v3
66 |         with:
67 |           path: ./public
68 | 
69 |   # Deployment job
70 |   deploy:
71 |     environment:
72 |       name: github-pages
73 |       url: ${{ steps.deployment.outputs.page_url }}
74 |     runs-on: ubuntu-latest
75 |     needs: build
76 |     steps:
77 |       - name: Deploy to GitHub Pages
78 |         id: deployment
79 |         uses: actions/deploy-pages@v4
80 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # Python Documentation Editorial Board
 2 | 
 3 | This repo contains activity updates, process, and planning information for the Python Documentation Editorial Board.
 4 | 
 5 | See [PEP 732](https://peps.python.org/pep-0732/).
 6 | 
 7 | ## Changelog
 8 | 
 9 | We have a "changelog" of decisions: [CHANGELOG.md](CHANGELOG.md). 
10 | 
11 | ## Updates
12 | 
13 | [Read updates](https://python.github.io/editorial-board/updates/) of the Editorial Board's activities.
14 | Subscribe to the updates using the [RSS feed](https://python.github.io/editorial-board/updates/index.xml).
15 | 
16 | ## Process
17 | 
18 | The Editorial Board's private meetings are monthly on the second Tuesday at 1:30pm Pacific.
19 | 
20 | If you have a general request or question, please use the [Documentation category in Discourse](https://discuss.python.org/c/documentation/26).
21 | 
22 | If you need Editorial Board assistance, please [file an issue on this repo](https://github.com/python/editorial-board/issues/new/choose).
23 | 
24 | ## Reference
25 | 
26 | These links give context on the editorial board:
27 | - [PEP 732](https://peps.python.org/pep-0732/)
28 | - [PEP 732 Discourse discussion](https://discuss.python.org/t/pep-732-the-python-documentation-editorial-board/36710)
29 | - [Language Summit 2021 presentation](https://pyfound.blogspot.com/2021/05/the-2021-python-language-summit-python.html)
30 | - [Language Summit 2020 presentation](https://pyfound.blogspot.com/2020/04/cpython-documentation-next-5-years.html)
31 | 
32 | These links give context on existing documentation landing pages:
33 | - [CPython Documentation Landing page (docs.python.org)](https://docs.python.org)
34 | - [PSF (python.org) website landing page](https://python.org)
35 | - [Documentation Experience presentation - Review navigation of PSF website related to docs](https://docs.google.com/presentation/d/1ujDv8wViPvAMFAtYCRxSKh-CMUlbjcfVYitsqEI2Ios)
36 | 
37 | 
38 | ## Writing new content
39 | 
40 | Hugo is not needed to be installed in order to write a new meeting minutes.
41 | 
42 | Write the meeting minutes a markdown file under ``content/updates/*.md``, commit, and
43 | create the pull request. A preview will then be generated on Netlify.
44 | 
45 | The meeting minutes should be written using template provided in [archetypes/updates.md](/archetypes/updates.md).
46 | 
47 | If you have Hugo installed, a new meeting minutes file can be created by typing on the command line:
48 | 
49 | ```
50 | hugo new content content/updates/newupdate.md
51 | ```
52 | 
53 | This will create the file under ``content/updates/newupdate.md``, and you can continue editing it.
54 | 
55 | (replace "newupdate.md" with the desired filename.)
56 | 
57 | ### Updating the Meeting Attendee List
58 | 
59 | The list of attendees is pulled from the ``"members"`` field in the frontmatter. By default, it lists all members
60 | of the Python Docs Editorial Board. If a member did not attend the meeting, remove from this list.
61 | 
62 | ## Building the static site locally
63 | 
64 | 1. First install Hugo.
65 | 
66 | 2. Run the command at the root of the repository:
67 | 
68 | ```
69 | hugo server
70 | ```
71 | 
72 | ## Writing new changelog
73 | 
74 | Use the template in [archetypes/changelog.md](archetypes/changelog.md).
75 | 
76 | The file can also be created using the command:
77 | 
78 | ```
79 | hugo new content content/changelog/newchangelog.md
80 | ```
81 | 
82 | It will create a new file under ``content/changelog/newchangelog.md``. (Replace "newchangelog.md" with the desired filename).
83 | 


--------------------------------------------------------------------------------
/archetypes/changelog.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | author: [""]
 3 | title: "Changelog: {{ .Date | dateFormat "Jan 2, 2006" }}"
 4 | date: "{{ .Date }}"
 5 | tags: ["changelog"]
 6 | categories: ["changelog"]
 7 | series: ["Changelog"]
 8 | ShowToc: false
 9 | TocOpen: false
10 | ---
11 | 


--------------------------------------------------------------------------------
/archetypes/default.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: ""
3 | date: "{{ .Date }}"
4 | ---
5 | 
6 | 


--------------------------------------------------------------------------------
/archetypes/updates.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | author: [""]
 3 | title: "Meeting Minutes: {{ .Date | dateFormat "Jan 2, 2006" }}"
 4 | date: "{{ .Date }}"
 5 | description: "Meeting Minutes from Python Docs Editorial Board: {{ .Date | dateFormat "Jan 2, 2006" }}"
 6 | summary: "Meeting Minutes from Python Docs Editorial Board: {{ .Date | dateFormat "Jan 2, 2006" }}"
 7 | tags: ["minutes"]
 8 | categories: ["minutes"]
 9 | series: ["Meeting Minutes"]
10 | ShowToc: false
11 | TocOpen: false
12 | members: ["Carol Willing", "Guido van Rossum", "Joanna Jablonski", "Mariatta", "Ned Batchelder"]
13 | ---
14 | 
15 | ### Agenda
16 | 
17 | 
18 | 
19 | 


--------------------------------------------------------------------------------
/assets/css/extended/custom.css:
--------------------------------------------------------------------------------
 1 | .entry-content{
 2 |     a{
 3 |         text-decoration: underline;
 4 |     }
 5 | }
 6 | 
 7 | #menu a{
 8 |     :not(.active) {
 9 |         text-decoration: underline;
10 |     }
11 | }
12 | 
13 | .entry-header {
14 |     text-decoration: underline;
15 | }
16 | 
17 | .archive-entry h3{
18 |     text-decoration: underline;
19 | }
20 | 
21 | .breadcrumbs a:hover{
22 |     text-decoration: underline;
23 | }
24 | 
25 | #members {
26 |   display: inline;
27 |   list-style: none;
28 | }
29 | 
30 | #members li {
31 |   display: inline;
32 | }
33 | 
34 | #members li:after {
35 |   content: ", ";
36 | }
37 | #members li:last-child:after {
38 |     content: "";
39 | }


--------------------------------------------------------------------------------
/content/archives.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Archive"
3 | layout: "archives"
4 | url: "/archives"
5 | summary: "archives"
6 | ---


--------------------------------------------------------------------------------
/content/changelog/2024-07-12-function-signatures.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | author: ["Ned Batchelder"]
 3 | title: "Function signatures include slash and star"
 4 | date: "2024-07-12"
 5 | tags: ["changelog"]
 6 | categories: ["changelog"]
 7 | series: ["Changelog"]
 8 | ShowToc: false
 9 | TocOpen: false
10 | ---
11 | 
12 | Function signatures should include slash and star: https://github.com/python/devguide/pull/1344
13 | 
14 | ## Summary
15 | 
16 | If a function accepts positional-only or keyword-only arguments, include the
17 | slash and the star in the signature as appropriate.
18 | 
19 | ```rst
20 | .. function:: some_function(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):
21 | ```
22 | 
23 | Although the syntax is terse, it is precise about the allowable ways to call
24 | the function and is taken from Python itself.
25 | 
26 | The CPython Devguide has been updated to reflect [this recommendation](https://devguide.python.org/documentation/style-guide/#function-signatures).
27 | 


--------------------------------------------------------------------------------
/content/changelog/2024-07-18-clarify-timezone.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | author: ["Ned Batchelder"]
 3 | title: "Timezone vs time zone"
 4 | date: "2024-07-18"
 5 | tags: ["changelog"]
 6 | categories: ["changelog"]
 7 | series: ["Changelog"]
 8 | ShowToc: false
 9 | TocOpen: false
10 | ---
11 | 
12 | Clarify `timezone` vs "time zone": https://github.com/python/devguide/pull/1352
13 | 
14 | ## Summary
15 | 
16 | The CPython PR [#118449](https://github.com/python/cpython/pull/118449) updates the spelling of "timezone" to "time zone".
17 | There was a discussion
18 | on the PR that the "timezone" spelling is also acceptable and have been used within the CPython docs
19 | consistently. However, both Wikipedia and The Free Dictionary redirect "timezone" to "time zone".
20 | 
21 | Using the two-word form "time zone" would help separate the concept from the "timezone" class in Python.
22 | 
23 | The [Style Guide](https://devguide.python.org/documentation/style-guide/#style-guide) section on CPython Devguide has
24 | now been updated with the recommendation of using the
25 | two word `time zone` when referring to the real-world time concept, and to use the one word `timezone` with
26 | appropriate code markup when referring to a Python term.
27 | 
28 | 


--------------------------------------------------------------------------------
/content/changelog/2024-08-28-style-guide-recs.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | author: ["Ned Batchelder"]
 3 | title: "Style Guide recommendations"
 4 | date: "2024-08-28"
 5 | tags: ["changelog"]
 6 | categories: ["changelog"]
 7 | series: ["Changelog"]
 8 | ShowToc: false
 9 | TocOpen: false
10 | ---
11 | 
12 | Additional recommendations in the Style Guide https://github.com/python/devguide/pull/1377/
13 | 
14 | ## Summary
15 | 
16 | The [Style Guide](https://devguide.python.org/documentation/style-guide/) has been updated with new
17 | recommendations about author attribution (don't include it) and pronunciation of dunder names ("an `__init__`, not `a __init__`).


--------------------------------------------------------------------------------
/content/changelog/2024-10-14-devguide-reorg.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | author: ["Mariatta"]
 3 | title: "Devguide Reorganization"
 4 | date: "2024-10-14"
 5 | tags: ["changelog"]
 6 | categories: ["changelog"]
 7 | series: ["Changelog"]
 8 | ShowToc: false
 9 | TocOpen: false
10 | ---
11 | 
12 | Refactoring the devguide into a Contribution Guide https://discuss.python.org/t/refactoring-the-devguide-into-a-contribution-guide/63409
13 | 
14 | ## Summary
15 | 
16 | We've started a large task to restructure the devguide to be more welcoming to non-code contributions.


--------------------------------------------------------------------------------
/content/changelog/2024-11-11-dead-batteries-docs.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | author: ["Mariatta"]
 3 | title: "Dead Batteries Docs"
 4 | date: "2025-03-11"
 5 | tags: ["changelog"]
 6 | categories: ["changelog"]
 7 | series: ["Changelog"]
 8 | ShowToc: false
 9 | TocOpen: false
10 | ---
11 | 
12 | History of dead batteries: https://discuss.python.org/t/history-of-dead-batteries/68934
13 | 
14 | Documenting Dead batteries: https://discuss.python.org/t/documenting-dead-batteries/70652
15 | 
16 | PR: https://github.com/python/cpython/pull/126622
17 | 
18 | ## Summary
19 | 
20 | The PR adds a "Removed modules" page that lists modules which have been removed. Each module gets a page (with the original URL) that explains why the module is gone.


--------------------------------------------------------------------------------
/content/changelog/2025-03-11-pipes-or-in-sphinx-type-descriptions.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | author: ["Mariatta"]
 3 | title: "``|`` or 'or' in parameter documentation"
 4 | date: "2025-03-11"
 5 | tags: ["changelog"]
 6 | categories: ["changelog"]
 7 | series: ["Changelog"]
 8 | ShowToc: false
 9 | TocOpen: false
10 | ---
11 | 
12 | Additional recommendations in the Style Guide https://github.com/python/devguide/pull/1377/
13 | 
14 | ## Summary
15 | 
16 | [Discourse](https://discuss.python.org/t/how-should-we-mark-up-multiple-types-in-a-type-field/48196) topic: How
17 | should we mark up multiple types in a type field?
18 | 
19 | Currently, the Python docs use `|` (pipe) character, similar to how you'd annotate a union of types:
20 | 
21 | ```rst
22 | :param p:
23 |    A parameter that takes an int or a float argument.
24 | :type p: int | float
25 | ```
26 | 
27 | However, the [Sphinx docs](https://www.sphinx-doc.org/en/master/usage/domains/python.html#send_message) says to use the word `or`:
28 | 
29 | ```rst
30 | :param p:
31 |    A parameter that takes an int or a float argument.
32 | :type p: int or float
33 | ```
34 | 
35 | The editorial board's decision was requested on this matter via [issue #7](https://github.com/python/editorial-board/issues/7).
36 | 
37 | The editorial board discussed this over several meetings, our decision is to use the `|` symbol. We met with Adam Turner
38 | to discuss how this would be implemented in Sphinx. This is supported in the latest version of Sphinx and the CPython
39 | docs have been built using the latest Sphinx.
40 | 
41 | 


--------------------------------------------------------------------------------
/content/changelog/_index.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Editorial Board Decisions"
3 | layout: "changelog"
4 | ---
5 | 
6 | Editorial Board Decisions
7 | 
8 | This is a running log of decisions taken by the Editorial Board.
9 | 


--------------------------------------------------------------------------------
/content/search.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Search"
3 | placeholder: Search demo site with full text fuzzy search ...
4 | layout: "search"
5 | ---


--------------------------------------------------------------------------------
/content/updates/2024-01-08-editorial-board-update.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | author: ["Carol Willing"]
  3 | title: "Meeting Minutes: January 8, 2024"
  4 | date: "2024-01-08"
  5 | description: "Meeting Minutes from Python Docs Editorial Board: January 8, 2024."
  6 | summary: "Meeting Minutes from Python Docs Editorial Board: January 8, 2024."
  7 | tags: ["minutes"]
  8 | categories: ["minutes"]
  9 | series: ["Meeting Minutes"]
 10 | ShowToc: false
 11 | TocOpen: false
 12 | members: ["Carol Willing", "Guido van Rossum", "Joanna Jablonski", "Mariatta", "Ned Batchelder"]
 13 | ---
 14 | 
 15 | ### Agenda
 16 | 
 17 | We discussed these questions and worked to answer them.
 18 | 
 19 | #### How often will we meet?
 20 | 
 21 | We will meet monthly on second Monday each month from 1:30-2:30pm Pacific.
 22 | 
 23 | We will work asynchronously most of the time.
 24 | 
 25 | Next meeting: February 12, 2024
 26 | 
 27 | #### What are our deliverables about process and decisions?
 28 | 
 29 | We will produce:
 30 | 
 31 | 1. Meeting Minutes: Working meeting notes will be summarized and published in repo after each meeting.
 32 | 2. Process and priorities
 33 |     * Decisions will be published in "Recommendation" documents. These would be short documents focused on one topic. They would be published in the repo.
 34 |     * Identify what the needs are for the specific section of docs. So that greater community can know the goals when they do sprints etc.
 35 |     * We can identify blocking factors and remove them.
 36 |     * We write outlines, and the community can write the content. It’s good because it encourages writing new docs instead of modifying existing ones. There have been a lot of big overhaul projects that got swamped by discussions.
 37 | 3. Agenda gathering for next meeting: Use an issue on the GitHub repo.
 38 | 4. Focus on content needs and improvements; tone and style guides (not restructuredText style but writing)
 39 | 5. From the docs landing page, do an annual assessment of each part and identify need/frequency of changes (could be the foundation of a high-level editorial calendar of needs - one section each month)
 40 | 6. *Idea:* incorporate algolia search to sphinx
 41 | 7. Python.org vs docs.python.org
 42 |     * We should limit ourselves to docs.python.org
 43 |     * Share recommendations to python.org for changes about making sure on python.org docs will go to docs.python.org. Reduce multiple paths to wiki and doc landing pages other than docs.python.org when refering to "docs"
 44 | 
 45 | #### Will we start implementing the five-year plan partly outlined in the [Language Summit 2020 presentation](https://pyfound.blogspot.com/2020/04/cpython-documentation-next-5-years.html), or do we need to reassess and set a different direction?
 46 | 
 47 | The goals mentioned in the first and second years sound great, but I think we should review and see what we want to tackle first.  It could be those goals, or other ones, or a mix.
 48 | 
 49 | ##### *Year 1 goals (from old presentation)*
 50 | 
 51 | * Governance and Workgroup: In progress; TODO: define how we work
 52 | * Tutorials: Discussion started about existing tutorial. TODO: Do we have one "official" tutorial? Pathways for getting started (relates to landing page)
 53 | * Language Translations: Seems to be going well; TODO: Identify any PyCon sprint focus areas
 54 | * Landing Page: Work in progress [Documentation Experience presentation](https://docs.google.com/presentation/d/1ujDv8wViPvAMFAtYCRxSKh-CMUlbjcfVYitsqEI2Ios/edit#slide=id.p) TODO: Work with PSF to remove links to old wiki. This is for many the first stop in finding Python docs.
 55 | 
 56 | ##### *Year 2 and beyond goals (from old presentation)*
 57 | 
 58 | * Evaluate effectiveness
 59 | * Documentation sprints
 60 | * Annual editorial review
 61 | 
 62 | ##### Selected priorities for the Editorial Board
 63 | 
 64 | * How we can make it easier for people to contribute to docs
 65 | * How to make the docs even more accessible
 66 | * Modernizing the docs: content, UX, or the mechanics?
 67 |   * Editorial board should lead the content priorities
 68 |   * Color change, theme, community can do it. (They probably should have a PEP tp the SC for major changes.)
 69 | * Better SEO
 70 | * Process for the community to ask and bring proposals to EB
 71 |   * Let's model this after the SC process
 72 | * Encourage more positive and constructive discussions in the Python docs community. Work to reduce lengthy arguments, which are sometimes hostile and dismissive.
 73 | * When disagreements are at an impasse, make decisions to reduce those blockages.
 74 | 
 75 | **Decisions about documentation can be undone more easily than with code.**
 76 | 
 77 | #### How will we stay in touch with the docs community?
 78 | 
 79 | Some people have already asked how they can be involved.
 80 | 
 81 | Generally, people want to help with writing documentation, so they should be involved with the docs community and not editorial board.
 82 | 
 83 | * Published meeting minutes. Clear "how to contact" us.
 84 | * We will create the Repo and issue templates.
 85 | * Individuals can create an issue to request the topic be added to the agenda. We will discuss at the next scheduled meeting time or asynchronously.
 86 | 
 87 | * Can people attend these Editorial Board meetings?
 88 | 
 89 |   No. We will use a similar process as the SC.
 90 | 
 91 | We discussed the following process considerations:
 92 | 
 93 | * Repo is public, but not meant for public discussions.
 94 | * Avoid situation where there are many open issues.
 95 | * Prefer discussion on Discourse with Documentation tag, instead of on the Editorial Board repo.
 96 | * Issue on the Editorial board will lead to discussions on that issue. Is that ok?
 97 | 
 98 |   We will follow the existing SC process:
 99 |   * Have discussion on Discourse first then link the to an issue on the Editorial Board repo.
100 |   * Any further discussions to continue on the Discourse, or privately by the Editorial Board.
101 |   * There is no further discussions/comments on the repo's issue.
102 | 
103 | #### What are the things that require the Editorial Board to act on?
104 | 
105 | * Conflicts on content
106 | * Conflicts on tone and style best practices
107 | * Review of existing documentation and outline editorial needs
108 | * Identify needs for new content
109 | * Identify needs for rewrites
110 | * Provide guidance and guidelines for changes
111 |   See for example, the recent pull request: [https://github.com/python/cpython/pull/107449/files](https://github.com/python/cpython/pull/107449/files) which touches on global style issues.
112 | 
113 | ### Action items
114 | 
115 | * Contact PSF infra/PSF board about python.org.
116 | * Create a REPO similar to steering-council: python/editorial-board
117 |   * Readme should point to the PEP for Editorial board to create. @Carol to add content.
118 | * Meeting notes: don’t need to include too much details. It doesn’t need review, comments.
119 | * Let’s create a new repo: python/editorial-board. Done. @editorial-board team was also created.
120 | * Need an issue template: on GitHub
121 |   * Need to submit their request into one of two big priorities:
122 |     * 1. Proposing a new idea
123 |     * 2. We need a decision of existing issue.
124 | 
125 | ### Resources
126 | 
127 | These links give context on the editorial board:
128 | 
129 | * [PEP 732](https://peps.python.org/pep-0732/)
130 | * [PEP 732 Discourse discussion](https://discuss.python.org/t/pep-732-the-python-documentation-editorial-board/36710)
131 | * [Language Summit 2021 presentation](https://pyfound.blogspot.com/2021/05/the-2021-python-language-summit-python.html)
132 | * [Language Summit 2020 presentation](https://pyfound.blogspot.com/2020/04/cpython-documentation-next-5-years.html)
133 | 
134 | These links give context on existing landing pages:
135 | 
136 | * [CPython Documentation Landing page (docs.python.org)](https://docs.python.org/3/)
137 | * [PSF (python.org) website landing page](https://python.org)
138 | * [Documentation Experience presentation](https://docs.google.com/presentation/d/1ujDv8wViPvAMFAtYCRxSKh-CMUlbjcfVYitsqEI2Ios/edit#slide=id.p) _[Work in Progress: Review of PSF landing page for docs]_
139 | 


--------------------------------------------------------------------------------
/content/updates/2024-02-12-editorial-board-update.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | author: ["Mariatta"]
  3 | title: "Meeting Minutes: February 12, 2024"
  4 | date: "2024-02-12"
  5 | description: "Meeting Minutes from Python Docs Editorial Board: February 12, 2024."
  6 | summary: "Meeting Minutes from Python Docs Editorial Board: February 12, 2024."
  7 | tags: ["minutes"]
  8 | categories: ["minutes"]
  9 | series: ["Meeting Minutes"]
 10 | ShowToc: false
 11 | TocOpen: false
 12 | members: ["Guido van Rossum", "Joanna Jablonski", "Mariatta", "Ned Batchelder"]
 13 | ---
 14 | 
 15 | ## Agenda
 16 | 
 17 | 1. What project do we want to deliver first? Here are some ideas to start the discussion:
 18 | 
 19 |    a. Define scope and outline for new intro tutorial
 20 |    b. Define scope and outline for new landing page
 21 |    c. Inventory/audit a section of the docs
 22 |    d. Personas (see #3 below)
 23 | 
 24 | 
 25 | 2. What does the docs community need from us most right now? Here are some ideas to start the discussion:
 26 | 
 27 |    - How-to discussion
 28 |    - First-person discussion 
 29 |    - A more thorough and more skimmable style guide
 30 | 
 31 | 3. [meta] Do we have a way to collect the largish topics they’ve discussed that we could provide guidance for? -> see editorial-board GH repo
 32 | 
 33 |    - Function parameters: bulleted or not
 34 |    - Examples: how to integrate into the docs
 35 |    - Type hints 
 36 | 
 37 | 4. Do we have an idea of what type of learner/user we need to optimize the docs for?
 38 | 
 39 |    - Wait until Carol is back 
 40 | 
 41 | 5. Do we have an idea of what type of contributor we want to prioritize removing obstacles for and creating systems for?
 42 | 
 43 | 6. Will the editorial board give an update at the language summit or PyCon?
 44 | 
 45 |    - The language summit isn’t even announced yet. We’ll think about it next time
 46 | 
 47 | ## Notes
 48 | 
 49 | 1. Let’s begin with a relatively small project. 1b from above. It is concrete, and we can propose implementation and refine it quickly.
 50 | 
 51 | 2. 2a is a bigger issue, but is important. (will affect 2b)
 52 | 
 53 | 3. Recommendation: don’t use first-person for new docs.
 54 | 
 55 | 4. Howto doc: we might preserve some historical content. Some docs may be marked as “historical doc”, keep them, but might get changed. Add a disclaimer at the top.
 56 | 
 57 | 5. Add reminder to future contributors not to use those as a template.
 58 | 
 59 | 6. PR churn. Docs changes don’t need to follow the same guidelines.
 60 | 
 61 | 7. Style guide:
 62 |    - In devguide now, update it
 63 |    - https://devguide.python.org/documentation/style-guide/
 64 |    - Some things should be in the style guide
 65 |    - First person, terminologies like master/slave, should be there
 66 |    - Big O notation should be in the Howto part of the style guide
 67 |    - The EB will own this (and create issues and PRs)
 68 |    - Should still be on devguide
 69 | 
 70 | 8. Discovery: 🔒 [Docs Style Guide](https://docs.google.com/document/d/1rSkUIGFuI5zDMYturyJCo9agYPQ-d53Z3MntSV0rB3E/edit#heading=h.hflx14peuyef)
 71 | 
 72 | 9. Mariatta to create a Gdrive folder to be shared with PDEB
 73 |    
 74 | 10. Need an announcement about https://github.com/python/editorial-board, that we're here. The readme should tell people how to be involved and how to ask for help.
 75 |    - On Discourse
 76 |    - In the README of docs-community GitHub repo
 77 |    - DevGuide
 78 |    - And PEP 732 
 79 | 
 80 | 11. Docs Discord server: we shouldn’t need to be the owner.
 81 |    
 82 | 12. Discuss: what type of learner we need to optimize the docs for?
 83 |     - We wait until Carol is back
 84 |     - We’ll start an async collaboration in a new Google Doc
 85 |     - There is a way to get notification of changes in Google Docs (need to be set up per-doc):
 86 |        - Click the “comment” button
 87 |        - Click the bell to set notifications: you can get notified of all content changes
 88 | 
 89 | 13. Do we have an idea of what type of contributor we want to prioritize removing obstacles for and creating systems for?
 90 |     - What are the types of contributors?
 91 |     - Core devs, triagers -> already know the way
 92 |     - For non core devs: First time OS contributor, vs experienced OS contributor
 93 |     - Non developers
 94 |     - Not-primarily english-speaking contributors
 95 | 
 96 | 14. Guido’s request: Not having links that are hidden unless you hover
 97 | 
 98 | 15. A tutorial on how to successfully contribute to the CPython docs.
 99 | 
100 | 16. CPython docs links to GitHub source code if clicked on the “Show Source” link. Is this good?
101 |     - Some pages get rendered (pprint.rst), some show as raw rst (functions.rst)
102 | 
103 | 17. What type of contributors who can make the biggest impact, that we are currently overlooking?
104 |     - Tech writers
105 |     - Challenge: who to listen to. PR reviews can be noisy. 
106 |     - Member vs Contributor 
107 |     - But what if even core devs conflict with each other. 
108 | 
109 | 18. Can we have volunteers/helpers to help people with pull requests?
110 |     - Could be similar to the Djangonauts: have someone who will help new contributors with PRs. Captains, navigators, etc
111 |     - Or less structured.
112 |     - Avoiding using the word “mentor” because it seems to be establishing a formal relationship
113 | 
114 | 
115 | ## Action items
116 | 
117 | * Style Guide:
118 |   Update the style guide with some new recommendations: first-person, terminologies
119 | * Ad campaign:
120 | 
121 | More detail on #10 of the above notes:
122 | * Start the async exploration of who our learners are 
123 | * Start the async explorations of what kind of contributors we want to help
124 | * Specify that Python wiki is out of scope in PEP 732: https://github.com/python/peps/pull/3663	
125 | 
126 | 


--------------------------------------------------------------------------------
/content/updates/2024-03-11-editorial-board-update.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | author: ["Mariatta"]
 3 | title: "Meeting Minutes: March 11, 2024"
 4 | date: "2024-03-11"
 5 | description: "Meeting Minutes from Python Docs Editorial Board: March 11, 2024."
 6 | summary: "Meeting Minutes from Python Docs Editorial Board: March 11, 2024."
 7 | tags: ["minutes"]
 8 | categories: ["minutes"]
 9 | series: ["Meeting Minutes"]
10 | ShowToc: false
11 | TocOpen: false
12 | members: ["Guido van Rossum", "Joanna Jablonski", "Mariatta", "Ned Batchelder"]
13 | ---
14 | 
15 | ### Agenda
16 | 
17 | 1. What project do we want to deliver first? Here are some ideas to start the discussion:
18 | 
19 |    a. Define scope and outline for new intro tutorial
20 |    b. Define scope and outline for new landing page
21 |    c. Inventory/audit a section of the docs
22 |    d. Define learner personas
23 | 
24 | 
25 | 2. What does the docs community need from us most right now? Here are some ideas to start the discussion:
26 | 
27 | - How-to discussion
28 | - First-person discussion 
29 | - A more thorough and more skimmable style guide
30 | 
31 | 3. [meta] Do we have a way to collect the largish topics they’ve discussed that we could provide guidance for? -> see editorial-board GH repo
32 | 
33 | - Function parameters: bulleted or not
34 | - Examples: how to integrate into the docs
35 | - Type hints 
36 | 
37 | 4. Do we have an idea of what type of learner/user we need to optimize the docs for?
38 |    - 🔒 [Discovery doc about learners](https://docs.google.com/document/d/1ILusuBaAoxUzm1NDOuiS3sZYePDVB5YcY7RoLkXyfI0/edit?usp=sharing)
39 |    - [Thoughts about growth in users and approach](https://discord.com/channels/1100135599077331024/1100135599077331028/1216838941723070534)
40 | 
41 | 5. Do we have an idea of what type of contributor we want to prioritize removing obstacles for and creating systems for?
42 | 
43 | 6. How do we decide on issues for our agenda?
44 |    Is e.g. https://github.com/python/cpython/pull/116595 suitable to discuss here?
45 | 
46 | 
47 | 
48 | ### Notes
49 | 
50 | Guido: We didn't actually go through that agenda at all.
51 | We discuss what our priorities are.
52 | We also didn't review last month's action items.
53 | 
54 | 
55 | 1. Python growth for the next decade will be driven by non CS folks, new users, non technical. 
56 | 2. Existing tutorial is the "what" 
57 | 3. Python has a rich ecosystem, you can get a lot of things done without needing the full scope of the stdlib. We should have more docs for it.
58 |    Example docs:
59 |    - https://github.com/sandiegopython/intro-to-python/ 
60 |    - Jessica McKellar’s intro: https://www.youtube.com/watch?v=rkx5_MRAV3A 
61 | 4. We need an introduction to Python docs. Current official Tutorial isn’t targeting new non-technical learners. They don’t know where to start. Other resources exist elsewhere. But it would be useful to have a beginner’s guide within docs.p.o
62 |    - Do we need to cover everything? Lots of people write guides to Python
63 |    - Official docs could have a curated list of useful docs. 
64 | 
65 | 5. Options:
66 |    - Better landing page?
67 |      * It needs to be better for newcomers, but also for people who are already experienced and already know their way around the docs.
68 |      * Come up with a refresh of the docs.python.org landing page, more user friendly and welcoming/inviting.
69 |      * Tooltips/ Guided tours -> need cookies.
70 |        Just provide a link instead of interactive.
71 |    - Action item:
72 |      * Look at front page of docs.p.o and decide which ones should be more prominent
73 |      * Come up with a short: (3 page) tutorial. Carol will start an outline. 
74 |      * Document our philosophy, explain the different target users and where they can find the docs they need.
75 |    - Glossary
76 |    - Define other user personas first?
77 | 6. Docs community meeting. Anything we should know?
78 |    - What to do with Changelog.
79 |    - Directives changes in the rst. Need to improve the devguide for it.
80 |    - Typographic markups. Still under discussion on Discourse. 
81 |    - Think about the outcome first and toolings next.
82 |    - Accessibility checking. UI/UX. Italics or not.
83 | 7. Ned is talking to a university professor who is building their own IDE/notebook. 
84 |    - They see this as a hurdle for teaching Python to students
85 | 


--------------------------------------------------------------------------------
/content/updates/2024-04-08-editorial-board-update.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | author: ["Mariatta"]
 3 | title: "Meeting Minutes: April 08, 2024"
 4 | date: "2024-04-08"
 5 | description: "Meeting Minutes from Python Docs Editorial Board: April 08, 2024."
 6 | summary: "Meeting Minutes from Python Docs Editorial Board: April 08, 2024."
 7 | tags: ["minutes"]
 8 | categories: ["minutes"]
 9 | series: ["Meeting Minutes"]
10 | ShowToc: false
11 | TocOpen: false
12 | members: ["Guido van Rossum", "Joanna Jablonski", "Mariatta", "Ned Batchelder"]
13 | ---
14 | 
15 | ### Agenda
16 | 
17 | 1. What will be our Doc Summit participation?
18 |    - Who will be attending? Carol, Ned
19 |    - Lightning talk: submit: https://docs.google.com/forms/d/e/1FAIpQLSe1n3YMIRnrWhoSSC29yM1w_IucgrY4D6RM3infhaNELFeJSg/viewform
20 |    - TODO: Carol will put together some bullets
21 | 2. Prepare an “elevator pitch” kind of thing for Editorial Board: it could just point to our repo too?
22 | 3. Advice: If you’re going to run a meeting, run the meeting (including cutting and moderating, stopping people from going on and on)
23 | 4. Bring up in next community call:
24 |    - Are there clear possibilities that you can share with the editorial board, so we can make a decision.
25 | 5. Carol or Ned to come up with the options.
26 | 6. Warning Sphinx?
27 |    - Multiple types: https://discuss.python.org/t/how-should-we-mark-up-multiple-types-in-a-type-field/48196/20
28 |      TODO: Ned will post on the thread to try to come to closure. What are the current options?
29 |    - WarningMessage is undocumented: https://discuss.python.org/t/warningmessage-is-undocumented/48877 
30 | 7. No meeting in May because of PyCon US. We’ll discuss async until June.
31 | 
32 | 


--------------------------------------------------------------------------------
/content/updates/2024-06-03-editorial-board-update.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | author: ["Mariatta"]
  3 | title: "Meeting Minutes: June 03, 2024"
  4 | date: "2024-06-03"
  5 | description: "Meeting Minutes from Python Docs Editorial Board: June 03, 2024."
  6 | summary: "Meeting Minutes from Python Docs Editorial Board: June 03, 2024."
  7 | tags: ["minutes"]
  8 | categories: ["minutes"]
  9 | series: ["Meeting Minutes"]
 10 | ShowToc: false
 11 | TocOpen: false
 12 | members: ["Carol Willing", "Guido van Rossum", "Joanna Jablonski", "Mariatta", "Ned Batchelder"]
 13 | ---
 14 | 
 15 | ### Old Action Items
 16 | 
 17 | Where are we with the action items from April 8?
 18 | 
 19 | 1. Bring up in the next community call: Are there clear possibilities that you can share with the editorial board, so we can make a decision?
 20 |     - Ned has been attending, but can’t tomorrow. They have not been coming up with things they want us to do.
 21 |     - Give them immediate feedback: we will decide if you create an issue.
 22 |     - Sometimes the problem isn't framed appropriately
 23 |     - Carol will attend tomorrow. 
 24 |     - Todo: be clear to the docs wg that we will decide if you open up a ticket
 25 | 
 26 | 2. Eric Matthes said: wants to see us have more guiding principles before getting involved,
 27 | 
 28 | 3. Todo: create a dir in the GitHub repo and move there?
 29 |    - Google Drive? 
 30 |    - Todo: move or link the docs to the GitHub repo
 31 |    
 32 | 4. NEW Action item: communicate the above to the next Docs Community meeting.
 33 | 
 34 | Where are we with the action items from March 11?
 35 | 1. Look at front page of docs.p.o and decide which ones should be more prominent
 36 | 2. Come up with a short: (3 page) tutorial. Carol will start an outline. 
 37 | 3. Document our philosophy, explain the different target users and where they can find the docs they need.
 38 | 
 39 | 
 40 | ### Agenda
 41 | 
 42 | 1. What action items are we taking from the discussion at the docs dinner?
 43 |    * Notes on contributing to docs:
 44 |      - Melanie’s notes: [Python Docs Contributing Adventure](https://docs.google.com/document/d/11zxisx5XfYOsrDOn4qd-XUSpDltIOi35qiOO9fDLfnI/edit#heading=h.1hkck4lqac8)
 45 |      - Shauna’s notes: [Python Docs Onboarding Notes](https://docs.google.com/document/d/1icjPpmEUH0BRPDwl7oXLkpasvwZoS5io2LyTEhblku0/edit)
 46 |      - Notes after discussion with Eric Matthes: [Guiding Principles for Documentation Editorial Board.md](https://drive.google.com/file/d/1elKNdRPTIoNe6EZ4TbS9aquM-RaNDgmc/view?usp=drive_link)
 47 |      - Sprint ideas from Carol's discussion: [Doc ideas.md](https://drive.google.com/file/d/17uGzCmFnUDBYGwsR9xmzEOGi4fOOSnOj/view?usp=drive_link)
 48 | 
 49 |    * Other notes from dinner: 
 50 |      - Should you learn Python
 51 |      - Cheatsheet for rST markup
 52 |      - Ned says: "Write how-tos for Trey"
 53 |      - Trey = priorities
 54 |      - Docs are shared resource
 55 |      - Add "Did you find this helpful"
 56 |      - Update "How to contribute to docs" in dev guide and perhaps in a more user friendly way
 57 |      - What to expect after a docs PR
 58 |      - Codespell run once by core devs then add to CI after
 59 |      - Message on PR template for docs that sets expectations for PR review
 60 |    
 61 |    * Action item: no clear path for contributing to CPython Docs. Devguide section is lacking, mostly for CPython code changes. 
 62 |    * New action item: the PDEB should write tickets for the action items on this meeting
 63 |    * Decision:
 64 |      - We are sticking with Rst for CPython docs.
 65 |      - Myst Parser: https://myst-parser.readthedocs.io/en/latest/
 66 |      - Mariatta has a talk: [Introduction to Sphinx Docs and reStructuredText](https://www.youtube.com/watch?v=v4eoYpCON_c) - Pyninsula #28
 67 |    * Action item:
 68 |      - Ned will write up an outline for “How to contribute to CPython Docs”
 69 | 
 70 | 2. What action items are we taking from the docs summit?
 71 |    none
 72 | 
 73 | 3. Do we have action items from the Docs Community?
 74 |    
 75 | 
 76 | 4. Is it time for us to focus on filling out these two docs so we can set a direction? Is there something else we should do first because it is either a higher priority or a prerequisite? Are there people in the Python community who have more formal experience with user research and might want to help?
 77 |    * Discovery doc about learners (Carol, would you like to capture your thoughts in this doc since you seem to have considered the issue deeply?) The Guiding Principles for Documentation Editorial Board.md captures the 3 user personas.
 78 |    * Discovery doc about contributors (Ned, would you like to capture your observations about the community in this doc since you seem to be the most involved with them?)
 79 |    * Action item: finish up the 🔒 [Guiding Principles](https://docs.google.com/document/d/1ILusuBaAoxUzm1NDOuiS3sZYePDVB5YcY7RoLkXyfI0/edit?usp=sharing) doc, and officially adopt it. To become the first page of the Docs Guide. To answer the “Discover Doc about Learners” Discovery Doc: Who is Our Learner
 80 | 
 81 | 5. Todo: form a WG to address packaging users docs
 82 | 
 83 | 6. Discussing the [Guiding Principles](https://drive.google.com/file/d/1elKNdRPTIoNe6EZ4TbS9aquM-RaNDgmc/view?usp=sharing)
 84 |    * How to ensure the novices are properly supported? 
 85 |    * Action item: Develop a user-journey. Tutorials, to be added outside of the actual Tutorials section. Eg including examples in references.
 86 |    * Who are our contributors?
 87 |      - Core devs. Code changes -> doc changes
 88 |      - Long-term docs contributors
 89 |      - Drive-by contributors
 90 |      - Translations
 91 |    * People writing dev docs professionally don’t wanna contribute to Open source docs?
 92 |    * Educators may have feedback too
 93 |    * As PDEb we can create a system to unblock contributors. Which type of contributors we want to focus on? #2: long-term docs contributors.
 94 |    * Action item: the doc outline. Share tools/cheatsheet of learning Sphinx/rst, etc
 95 |      - Note:  the logistics of splitting up docs sections will be a big project
 96 |    * Action item:
 97 |      - Pull out docs-related from devguide as a (git) subtree
 98 |    * There are a lot of undocumented Docs tooling. Should write it up?
 99 | 
100 | 7. Next meeting: vacations, EuroPython.
101 |    * Cancel July, and meet August 12.
102 | 


--------------------------------------------------------------------------------
/content/updates/2024-08-12-editorial-board-update.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | author: ["Mariatta"]
 3 | title: "Meeting Minutes: August 12, 2024"
 4 | date: "2024-08-12"
 5 | description: "Meeting Minutes from Python Docs Editorial Board: August 12, 2024."
 6 | summary: "Meeting Minutes from Python Docs Editorial Board: August 12, 2024."
 7 | tags: ["minutes"]
 8 | categories: ["minutes"]
 9 | series: ["Meeting Minutes"]
10 | ShowToc: false
11 | TocOpen: false
12 | members: ["Mariatta", "Ned Batchelder"]
13 | ---
14 | 
15 | ### Old Action Items
16 | 
17 | Where are we with the action items from June 3?
18 | - [Create a dir in the GitHub repo and move there?](https://github.com/python/editorial-board/issues/5) Move or link the docs to the GitHub repo? Communicate this at the next Docs Community meeting
19 | - DONE: Ned will write up an outline for [“How to contribute to CPython Docs”](https://github.com/python/editorial-board/issues/4)
20 | - [Finish up the Guiding Principles doc](https://github.com/python/editorial-board/issues/10), and officially adopt it. To become the first page of the Docs Guide
21 | - [Form a WG to address packaging users docs](https://github.com/python/editorial-board/issues/11)
22 | 
23 | 
24 | 
25 | ### Agenda
26 | 
27 | 1. What should we accomplish before our next call?
28 | 2. Migrate documents from Google Drive to GitHub?
29 | 3. Next steps for docs guide?
30 | 4. Next steps for Guiding Principles doc?
31 | 5. Next steps for wg to address packaging user docs?
32 | 
33 | ### Notes
34 | 
35 | We did not go through the planned agenda, but Mariatta and Ned discussed the new outline for DevGuide.
36 | 
37 | #### New outline for devguide / contribution guide
38 | 
39 | Proposed outline for combined guide: https://docs.google.com/document/d/1Ajk_Vj3rccJ9ReB7WCNhEnLHQP23iMg7jAFQ-CYKzWo/edit
40 | 
41 | ##### Next steps:
42 | 
43 | - Create devguide project
44 | 
45 | - Write devguide issues
46 |   * Overall restructure, with placeholder sections, according to the Google Doc.  No need to write content.  Placeholder pages can include bullets about the topics to be covered there.  Placeholder pages can have a boilerplate info box explaining that the page is in-progress.
47 |   * Write issues for each section that needs to be fleshed out.
48 | 
49 | - Question: We propose to publish the new-organization skeleton as the devguide while we flesh it out.  Ask in PDEB Discord if anyone objects.  We want to keep it simple, so no branch, publish the placeholders
50 |   * It will be for a short time
51 |   * Don’t want to maintain a long-lived branch
52 |   * Raises the visibility of the work
53 |   * Encourages contribution
54 | - Set a target date for when this is done
55 |   * Aim to have it done by May 2025 for PyCon US
56 |   * Maybe a sprint at PyCon to get it over the line
57 | 


--------------------------------------------------------------------------------
/content/updates/2024-09-09-editorial-board-update.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | author: ["Mariatta"]
 3 | title: "Meeting Minutes: September 09, 2024"
 4 | date: "2024-09-09"
 5 | description: "Meeting Minutes from Python Docs Editorial Board: September 09, 2024."
 6 | summary: "Meeting Minutes from Python Docs Editorial Board: September 09, 2024."
 7 | tags: ["minutes"]
 8 | categories: ["minutes"]
 9 | series: ["Meeting Minutes"]
10 | ShowToc: false
11 | TocOpen: false
12 | members: ["Carol Willing", "Guido van Rossum", "Mariatta", "Ned Batchelder"]
13 | ---
14 | 
15 | ## Notes
16 | 
17 | * Discuss past action items.
18 | * Catch up about last month:
19 |     * Outline about the DevGuide 
20 |     * DevGuide GitHub project (who will create?)
21 |     * Write the issues (who will write?)
22 |     * Do we publish changes as they are ready, or do we wait until entire reorg is finished?
23 |         * What about existing URLs? (urls from other existing pages)
24 |         * Since we are on readthedocs, it can be mapped from there -> redirect to new pages
25 |         * You can mark pages as orphaned on Sphinx(?) Cam/Hugo might know
26 |         * Do we need to convince others about this approach?
27 | * Publicize the fact that we are actively reorganizing the DevGuide into Contribution Guide (~~TODO: Ned will start a Discourse thread, and will send a link~~)
28 |   * Done https://discuss.python.org/t/refactoring-the-devguide-into-a-contribution-guide/63409
29 | * Some things that document what’s changed between Python versions are better off in the same VCS as the code. Things in the current DevGuide are like that.
30 |   * So we need to define what belongs in Contrib Guide vs CPython docs.
31 |   * Example: Irit’s project is better documented within CPython’s doc. Tracked in https://github.com/python/cpython/issues/119786
32 | * We should go into detail: what our workflow is, and explain where to go for different docs, where are things documented.
33 | * We like the idea of publishing in progress. Unsure about url remapping right away.
34 | * Are we still using the “devguide” sub url? -> should it be “contributing” subdomain.
35 |   * “Devguide” is well known terminology among existing contributors.
36 |   * “Contributors” vs “contributing” . python org url -> can cause confusion when typing out the url
37 |   * We like “contrib” contrib.python.org is chosen as the new url.
38 |   * Ticket created at https://github.com/python/devguide/issues/1393
39 | * Adding a big banner on top saying this doc is being actively re-org.
40 | * We might not want to render pages that are not really ready to be published. (by adding to conf.py ignores)? But also why not render those? When will we render those?
41 | * Another idea: add new pages to main branch, add to “do not render” list, have 2 different rtd sites built using the same repo, different config.
42 | * Sphinx has “if” conditional 
43 | * Who’s available and can do this work during the Sprint? 
44 |     * Mariatta, Ned (remotely)?
45 | * There will be a period of when both versions exist, and we want to keep this period short.
46 | * Tools available to make both versions work. 
47 | 


--------------------------------------------------------------------------------
/content/updates/2024-10-14-editorial-board-update.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | author: ["Mariatta"]
 3 | title: "Meeting Minutes: Oct 14, 2024"
 4 | date: "2024-10-14"
 5 | description: "Meeting Minutes from Python Docs Editorial Board: October 14, 2024"
 6 | summary: "Meeting Minutes from Python Docs Editorial Board: October 14, 2024"
 7 | tags: ["minutes"]
 8 | categories: ["minutes"]
 9 | series: ["Meeting Minutes"]
10 | ShowToc: false
11 | TocOpen: false
12 | members: ["Carol Willing", "Guido van Rossum", "Mariatta", "Ned Batchelder"]
13 | ---
14 | 
15 | ### Agenda
16 | 
17 | * Contribution Guide progress
18 | * Modernizing Python Docs
19 | 
20 | ### Notes
21 | 
22 | 
23 | * Contribution Guide progress
24 |     * PR created, approved.
25 |         * PR build: [https://cpython-devguide--1426.org.readthedocs.build/](https://cpython-devguide--1426.org.readthedocs.build/) 
26 |         * PR: [https://github.com/python/devguide/pull/1426](https://github.com/python/devguide/pull/1426)	
27 |     * Status:
28 |         * There is a new section within the current Devguide: “(draft)” item on the left menu.
29 |     * How do we feel about it landing on main right now?
30 |         * Worried about people ending up in the draft accidentally and thought it’s the real one.
31 |         * There is an info box at the top of each contrib guide saying it’s a WIP. 
32 |         * Example: [https://cpython-devguide--1426.org.readthedocs.build/contrib/intro/](https://cpython-devguide--1426.org.readthedocs.build/contrib/intro/)	there is a box at the top.
33 |         * [Ned TODO] Add the plan of this new contrib guide under “Introduction”
34 |         * [Ned TODO] embolden the section head in side bar also.
35 |     * How can people discover this?
36 |         * [devguide.python.org/contrib](devguide.python.org/contrib)
37 |         * Or look for the menu item
38 |     * Concerns with merging
39 |         * Linking concerns?
40 |         * Plan: flesh out the pages that don’t exist first. Then move things around later?
41 |         * We use Sphinx include directives.
42 |     * Make sure existing devguide maintainers and docs wg community take one last look
43 |         * Hugo, Jelle, Ezio, Petr
44 |     * DevGuide landing page, has a Quick Reference. It goes straight to code contribution. Feedback from people: it’s not relevant to doc contribution. Need a better pathway.
45 |     * Move the Quick reference to the code contribution. 
46 |     * On the landing page there is the table for contribution paths, we can move that up.
47 |         * Instead of table with many rows, it could be a table with two rows and bullet lists.
48 |         * We could use tabs too?
49 |     * What’s the next steps after merging?
50 |         * Ned will write up the plan
51 |         * Talk to people mentioned above
52 |         * Merge the PR
53 |         * More todo items from above
54 |         * Get feedback from people interested in writing sections and see it grow
55 |     * Do people want to be “codeowners” on the new contrib guide?
56 |         * Maybe eventually
57 | 
58 | * Modernizing Python Docs (Mariatta)
59 |     * Inspiration [https://docs.astro.build](https://docs.astro.build)
60 |     * tutorials.python.org built with new content and new tech
61 |     * What is the vision?
62 |     * Guido would like to see a smaller project using this new/other technology.
63 |     * We can frame it as “PDEB wants to try things out and will solicit feedback from the community.”
64 |     * Maybe take existing tutorials/how to and see how it works on this new tech.
65 |     * See also [https://mystmd.org/](https://mystmd.org/)
66 |       * Alternative tech that has JS interactivity
67 |     * Start with a small prototype of a tutorial
68 |         * Slice tutorial?
69 | 
70 | 
71 | 


--------------------------------------------------------------------------------
/content/updates/2024-11-11-editorial-board-update.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | author: ["Mariatta"]
 3 | title: "Meeting Minutes: Nov 11, 2024"
 4 | date: "2024-11-11"
 5 | description: "Meeting Minutes from Python Docs Editorial Board: November 11, 2024"
 6 | summary: "Meeting Minutes from Python Docs Editorial Board: November 11, 2024"
 7 | tags: ["minutes"]
 8 | categories: ["minutes"]
 9 | series: ["Meeting Minutes"]
10 | ShowToc: false
11 | TocOpen: false
12 | members: ["Guido van Rossum", "Mariatta", "Ned Batchelder"]
13 | ---
14 | 
15 | ### Agenda
16 | 
17 | * Contrib guide latest PR: [https://github.com/python/devguide/pull/1467](https://github.com/python/devguide/pull/1467)
18 |     * What does Triaging mean?
19 |         * It’s a specific role with permissions
20 |     * Make the order of the columns: docs, code, triaging
21 |     * Keep pushing forward
22 | * Removing dead batteries doc
23 |     * Discussion: [https://discuss.python.org/t/documenting-dead-batteries/70652/10](https://discuss.python.org/t/documenting-dead-batteries/70652/10)
24 |     * PR: [https://github.com/python/cpython/pull/126622](https://github.com/python/cpython/pull/126622) 
25 | * Reviewing what PEP 732 says about the structure of the PDEB
26 | 
27 | 
28 | 
29 | 
30 | 


--------------------------------------------------------------------------------
/content/updates/2024-12-10-editorial-board-update.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | author: ["Mariatta"]
 3 | title: "Meeting Minutes: Dec 10, 2024"
 4 | date: "2024-12-10"
 5 | description: "Meeting Minutes from Python Docs Editorial Board: December 10, 2024"
 6 | summary: "Meeting Minutes from Python Docs Editorial Board: December 10, 2024"
 7 | tags: ["minutes"]
 8 | categories: ["minutes"]
 9 | series: ["Meeting Minutes"]
10 | ShowToc: false
11 | TocOpen: false
12 | members: ["Guido van Rossum", "Mariatta", "Ned Batchelder"]
13 | ---
14 | 
15 | ### Notes
16 | 
17 | 
18 | * Is what we’re doing fulfilling the purpose of the EB?
19 |     * We have been very casual 
20 |     * We can be more proactive instead of waiting to be asked for a decision.
21 |     * Tables vs two-line summary: [https://discord.com/channels/935215565872693329/935215566334079058/1313842986836037683](https://discord.com/channels/935215565872693329/935215566334079058/1313842986836037683)
22 |     * Indecisions about docs are blocking contributions
23 |     * Diataxis says to make plans and decisions, not sweeping changes
24 | * Log of decisions:
25 |     * We have the changelog [https://python.github.io/editorial-board/changelog/](https://python.github.io/editorial-board/changelog/)
26 |     * People might want a one-size-fits-all decisions but 
27 | * Churns for docs is different with code churns
28 |     * Maybe we’d be more open to it? 
29 | * We can be more proactive instead of reactive
30 |     * Still mention that please don’t make PRs just to make sweeping changes to conform to the new styling decisions
31 |     * How to be more proactive: just be more active on the Docs discourse. We can say “the board discussed it and …”
32 | * Docs audit?
33 |     * Get more of a plan on how to proceed from Joanna
34 |     * Docs needing fixing: Argparse, asyncio, Threading (incl. concurrent.futures)
35 | * Request decision
36 |     * Request for decision: how should we mark up types in parameter lists?
37 |     * [https://github.com/python/editorial-board/issues/7](https://github.com/python/editorial-board/issues/7) 
38 |     * Make it a formal decision:
39 |         * Use the word or instead of |
40 |         * Instead of | None, use “optional”?
41 |         * Use “default” instead of “optional”
42 | * We are moving to Tuesdays
43 |     * Next meeting is Tuesday Jan 14
44 | * We should discuss docs issues more instead of personal projects
45 | 


--------------------------------------------------------------------------------
/content/updates/2025-01-14-editorial-board-update.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | author: ["Mariatta"]
 3 | title: "Meeting Minutes: Jan 14, 2025"
 4 | date: "2025-01-14"
 5 | description: "Meeting Minutes from Python Docs Editorial Board: January 14, 2025"
 6 | summary: "Meeting Minutes from Python Docs Editorial Board: January 14, 2025"
 7 | tags: ["minutes"]
 8 | categories: ["minutes"]
 9 | series: ["Meeting Minutes"]
10 | ShowToc: false
11 | TocOpen: false
12 | members: ["Guido van Rossum", "Joanna Jablonski", "Ned Batchelder"]
13 | ---
14 | 
15 | ### Agenda
16 | 
17 | 
18 | * [https://discuss.python.org/t/getopt-and-optparse-vs-argparse/69618/123](https://discuss.python.org/t/getopt-and-optparse-vs-argparse/69618/123)
19 | 
20 | ### Notes
21 | 
22 | 
23 | * Revisiting the “how to mark up types” discussion: [https://discuss.python.org/t/how-should-we-mark-up-multiple-types-in-a-type-field/48196/30](https://discuss.python.org/t/how-should-we-mark-up-multiple-types-in-a-type-field/48196/30)
24 |     * Erlend said “int or float” (our slight preference) would cause a syntax error for attributes in Sphinx.
25 |     * Ned’s quick experiment didn’t cause a syntax error
26 |     * Ned has pinged Erlend in Discord for a clarifying conversation.
27 |     * If it is a tooling issue, we will rule in favor of “int | float”
28 |         * Otherwise, we can rule for “int or float”
29 | * [https://discuss.python.org/t/getopt-and-optparse-vs-argparse/69618/123](https://discuss.python.org/t/getopt-and-optparse-vs-argparse/69618/123)
30 |     * Savannah mentioned an audit
31 |     * Joanna will respond on Discourse, inviting Savannah to participate in a docs audit of the argparse pages.
32 |     * Starting point:
33 |         * Two potential user journeys:
34 |           * Making something more basic. Have flags, take in files
35 |             * Making something with subcommands, like git. How do you structure that?
36 |             * Make them part 1 and part 2 of a how-to?
37 | 
38 |         * Main docs link to how-to(s) with user journeys + reference docs
39 |     * We’ve long aspired to doing docs audits, this could be a good baby step
40 |         * It is small enough to be approachable
41 |         * It can be a way to educate people about what docs audits are and how to do them
42 |         * It can be a way for us to reach agreement on how we will do docs audits
43 |     * User personas
44 |         * How much of this is needed before starting an audit?
45 | 


--------------------------------------------------------------------------------
/content/updates/2025-02-11-editorial-board-update.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | author: ["Mariatta"]
 3 | title: "Meeting Minutes: Feb 11, 2025"
 4 | date: "2025-02-11"
 5 | description: "Meeting Minutes from Python Docs Editorial Board: February 11, 2025"
 6 | summary: "Meeting Minutes from Python Docs Editorial Board: February 11, 2025"
 7 | tags: ["minutes"]
 8 | categories: ["minutes"]
 9 | series: ["Meeting Minutes"]
10 | ShowToc: false
11 | TocOpen: false
12 | members: ["Guido van Rossum", "Joanna Jablonski", "Mariatta", "Ned Batchelder"]
13 | guests: ["Adam Turner"]
14 | ---
15 | 
16 | ### Agenda
17 | 
18 | 
19 | * Doc audit
20 | * [https://github.com/sphinx-doc/sphinx/pull/13242](https://github.com/sphinx-doc/sphinx/pull/13242) -- technicalities about 'or' vs. '|' in Sphinx ':type:' constructs. There appears to be growing support for sticking with '|'
21 | * Star/Slash in function signatures
22 | 
23 | ### Notes
24 | 
25 | 
26 | 
27 | * Docs audit for argparse: see the “Docs Audit: argparse” doc in resources
28 |     * Looks like a good start
29 |     * Joanna and Savannah will be collaborating on this in the doc at first
30 |         * With some updates in the EB Discord
31 |     * They don’t currently need anything from the Board at the moment
32 |         * They will pull us in if needed
33 | * Pipes vs “or” in Sphinx type descriptions?
34 |     * [https://discuss.python.org/t/how-should-we-mark-up-multiple-types-in-a-type-field/48196/30](https://discuss.python.org/t/how-should-we-mark-up-multiple-types-in-a-type-field/48196/30)
35 |     * Adam Turner joins to help
36 |     * Adam’s view: we should adopt type annotation syntax
37 |         * When that doesn’t work (no type, or “file-like”, etc) we should leave the annotation blank, but still write out the English
38 |         * There are three places type information can appear:
39 |             * The function signature, which should look like Python code
40 |                 * If an argument is “file like”, it should be omitted here.
41 |             * The argument bullet list
42 |                 * This is the awkward place: types are parsed here with AST.
43 |                     * Sphinx possibilities:
44 |                         * Allow quoted strings, omit the quotes when rendering, and cross-link if the term is in the glossary.
45 |                         * Try to parse with AST, if it fails, parse with tokenize
46 |             * English prose in paragraph form
47 |                 * If an argument is “file like”, it should be fully described here.
48 |     * Plan:
49 |         * For non-formal types, use glossary cross-references
50 |         * Use pipes instead of prose where possible
51 |         * Implementation
52 |             * Allow quoted strings as the type annotation
53 |             * Unify parsing of field-list style and annotation-style
54 |             * Start with custom code for CPython to not have to wait for Sphinx release
55 |             * But goal is to upstream it to Sphinx
56 |         * Update the discuss.python.org thread with the decision.
57 | * Star/Slash in function signatures
58 |     * We want signatures to be precise: if arguments are positional, use a slash, even if there is only one argument.
59 |     * We will experiment with Sphinx tooling to provide a link on the slash and star.
60 |     * We looked at underline for slash, it was distracting and drew attention to the slash, when most people argue that the slash is already too distracting
61 |     * Hover text is a good fallback if a link isn’t an option.
62 | 
63 | 


--------------------------------------------------------------------------------
/content/updates/2025-03-11-editorial-board-update.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | author: ["Mariatta"]
 3 | title: "Meeting Minutes: Mar 11, 2025"
 4 | date: "2025-03-11T14:11:49-07:00"
 5 | description: "Meeting Minutes from Python Docs Editorial Board: Mar 11, 2025"
 6 | summary: "Meeting Minutes from Python Docs Editorial Board: Mar 11, 2025"
 7 | tags: ["minutes"]
 8 | categories: ["minutes"]
 9 | series: ["Meeting Minutes"]
10 | ShowToc: false
11 | TocOpen: false
12 | members: ["Carol Willing", "Guido van Rossum", "Joanna Jablonski", "Mariatta", "Ned Batchelder"]
13 | ---
14 | 
15 | ### Agenda
16 | 
17 | * [Docs audit with Savanna](https://docs.google.com/document/d/10MSDlxmgPex3ZGVr-4OggI2lqSAlv_0OTDchGlrLIkk/edit?usp=sharing) is on hold while she deals with other commitments
18 | * [https://github.com/python/editorial-board/issues/25](https://github.com/python/editorial-board/issues/25) (translation management) (issue is closed)
19 | 
20 | ### Notes
21 | 
22 | * Wiki:
23 |     * Carol went to Docs WG meeting last week. Discussion about the wiki. It is outside of EB’s focus. But we should not link to the wiki from Python docs.
24 |     * It would be great to have an Educational Landing page -> for a Python user, it would be better to have it instead of the wiki.python.
25 |     * Wiki is not a PSF-owned infrastructure? 
26 |     * We have many links (~20) to the wiki from cpython repo. Most were old what’s new docs.
27 |     * We will update and unlink (?)
28 |     * Maybe write in Devguide about the status about wiki.p.o. It is a community-run resource, it has implied authority beyond its actual authority.
29 | * Translations is doing well, now there is a translations dashboard https://python-docs-translations.github.io/dashboard/
30 | * Issue 25 is now closed, opened a Discourse instead [https://discuss.python.org/t/pep-545-update-pep/83534/](https://discuss.python.org/t/pep-545-update-pep/83534/)
31 | * There is now typing.python.org 
32 |     * Why is it separate from docs.python.org?
33 |     * It’s maintained by typing council.
34 |     * A set of standards for type checkers (which are not maintained by Python core)
35 |     * Should we explain all the different (something).python.org -> specifically wiki and typing
36 |     * Add writeup in devguide about which ones are Core Python docs, and there are things like packaging.
37 |     * Should we add typing.python.org as “not in scope” in our charter doc?
38 |     * The typing.p.o docs aren't tied to CPython version
39 | * Carol received comment from a Linux conference attendee, last few Python releases have been easy to install.
40 | * Ned is still going on with Devguide reorg (Initially we set a due date to get it done by PyCon US - PyCon US is in 2 months)
41 | *  “Or” vs “|” in the docs. 
42 |     * Feb 11 notes: prefer | instead of “or”. We should write it to our changelog [https://github.com/python/editorial-board/blob/main/CHANGELOG.md](https://github.com/python/editorial-board/blob/main/CHANGELOG.md)
43 |     * [https://github.com/python/editorial-board/issues/7](https://github.com/python/editorial-board/issues/7) 
44 |     * It depends on the Sphinx’ capability. It is supported in latest Sphinx and docs are now built using latest Sphinx.
45 | * Need to go back in our notes and backfill the Changelog.md file
46 | * The Docs WG are to ask the PSF to pay for the translation tools.
47 | 
48 | 


--------------------------------------------------------------------------------
/content/updates/2025-04-08-editorial-board-update.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | author: ["Mariatta"]
 3 | title: "Meeting Minutes: Apr 8, 2025"
 4 | date: "2025-04-08T14:49:46-07:00"
 5 | description: "Meeting Minutes from Python Docs Editorial Board: Apr 8, 2025"
 6 | summary: "Meeting Minutes from Python Docs Editorial Board: Apr 8, 2025"
 7 | tags: ["minutes"]
 8 | categories: ["minutes"]
 9 | series: ["Meeting Minutes"]
10 | ShowToc: false
11 | TocOpen: false
12 | members: ["Carol Willing", "Joanna Jablonski", "Mariatta", "Ned Batchelder"]
13 | ---
14 | 
15 | ### Agenda
16 | 
17 | * [Docs audit with Savannah](https://docs.google.com/document/d/10MSDlxmgPex3ZGVr-4OggI2lqSAlv_0OTDchGlrLIkk/edit?usp=sharing) is on hold while she deals with other commitments. She has plans to work on it in the next couple months.
18 | * Language Summit
19 | 
20 | ### Notes
21 | 
22 | * Language Summit: we have 30 minutes slot to engage with the core team. What are we gonna do?
23 |     * Mariatta, Carol, and Guido will be there
24 |     * Our updates: 
25 |         * Not much has happened, docs community have been active 
26 |         * There have been a few big decisions
27 |         * Decrease in “entitlement/ownership” of specific docs areas
28 |         * Having a named body has calmed down those and set a tone
29 |     * Start with the positives we’ve seen with docs, it’s more collaborative now
30 |         * Compare with when we started years ago
31 |         * “How it works” documentation moved into code
32 |         * Renewed emphasis on translations, usability, Irit’s work with moving some docs from devguide to code, Ned’s devguide refactoring
33 |         * Sqlite3 docs in Diátaxis spirit
34 |         * Docs audit with Joanna and Savannah
35 |         * Posting meeting minutes
36 |         * Seeing engagements with people outside of Core team
37 |         * Separate Docs Discord server works well
38 |     * Looking forward, vision and future
39 |         * We are here to unblock docs decisions
40 |         * Wiki. Is it not a PSF asset? (It is not)
41 |         * Should CPython’s involvement in docs be Reference docs and Devguide docs?
42 |           * To unblock other efforts such as translations of Docs tutorial. Should it be a PSF thing?
43 |           * Why not Core team’s thing?
44 |           * Maybe could free up funding opportunities if it is a PSF thing.
45 |           * Talk about “How PSF can be more involved with Python docs?” 
46 |         * Tutorial, onboarding, etc maybe more suited outside core team.
47 |         * Core team docs should just be Reference docs?
48 |     * How to ensure docs discussion is productive at the language summit
49 |         * Not the nitty gritty about the past decisions
50 |         * Focus on role of Core team, PSF, vision
51 |         * Mention the Education & outreach WG
52 |     * Who are we serving, how do we serve them
53 |         * Main audiences: Docs community, Python users, new users
54 |     * What else core team expect from us?
55 |     * What do we want to achieve?
56 |     * Mariatta to start some slides (maybe not until May)
57 | * Docs audit is still on hold. Might sprint at PyCon US.
58 | * Review our Changelog:
59 |     *  [https://deploy-preview-28--pythoneditorialboard.netlify.app/changelog/](https://deploy-preview-28--pythoneditorialboard.netlify.app/changelog/)
60 |     *  [https://github.com/python/editorial-board/pull/28](https://github.com/python/editorial-board/pull/28)
61 |     *  Actually, a lot has happened with Editorial board! 


--------------------------------------------------------------------------------
/go.mod:
--------------------------------------------------------------------------------
1 | module github.com/python/editorial-board
2 | 
3 | go 1.12
4 | 
5 | require github.com/adityatelange/hugo-PaperMod v0.0.0-20250301152106-e2e1011bdeca // indirect
6 | 


--------------------------------------------------------------------------------
/hugo.yaml:
--------------------------------------------------------------------------------
  1 | baseURL: "https://python.github.io/editorial-board/"
  2 | title: Python Docs Editorial Board
  3 | copyright: "© [Python Docs Editorial Board and Contributors](https://github.com/python/editorial-board/graphs/contributors)"
  4 | pagination:
  5 |   pagerSize: 10
  6 | 
  7 | enableInlineShortcodes: true
  8 | enableRobotsTXT: true
  9 | buildDrafts: false
 10 | buildFuture: false
 11 | buildExpired: false
 12 | enableEmoji: true
 13 | pygmentsUseClasses: true
 14 | mainsections: ["updates"]
 15 | 
 16 | minify:
 17 |   disableXML: true
 18 | 
 19 | outputs:
 20 |   home:
 21 |     - HTML
 22 |     - RSS
 23 |     - JSON # necessary for search
 24 | 
 25 | params:
 26 |   env: production # to enable google analytics, opengraph, twitter-cards and schema.
 27 |   description: "Python Docs Editorial Board (PEP 732)"
 28 |   author: Python Docs Editorial Board
 29 |   # author: ["Me", "You"] # multiple authors
 30 | 
 31 |   defaultTheme: auto
 32 |   # disableThemeToggle: true
 33 |   ShowShareButtons: true
 34 |   ShowReadingTime: false
 35 |   # disableSpecial1stPost: true
 36 |   displayFullLangName: true
 37 |   ShowPostNavLinks: true
 38 |   ShowBreadCrumbs: true
 39 |   ShowCodeCopyButtons: true
 40 |   ShowRssButtonInSectionTermList: true
 41 |   ShowAllPagesInArchive: true
 42 |   ShowPageNums: true
 43 |   ShowToc: true
 44 | 
 45 |   homeInfoParams:
 46 |     Title: "Python Docs Editorial Board"
 47 |     Content: >
 48 |      This site contains activity updates, process, and planning information for the Python Documentation Editorial Board.
 49 |       
 50 |      See [PEP 732](https://peps.python.org/pep-0732/).
 51 |       
 52 |      The Editorial Board's private meetings are monthly on the second Tuesday at 1:30pm Pacific.
 53 | 
 54 |      If you have a general request or question, please use the [Documentation category in Discourse](https://discuss.python.org/c/documentation/26).
 55 | 
 56 |      If you need Editorial Board assistance, please [file an issue on this repo](https://github.com/python/editorial-board/issues/new/choose).
 57 |   
 58 | 
 59 |   socialIcons:
 60 |     - name: github
 61 |       title: View Source on Github
 62 |       url: "https://github.com/python/editorial-board"
 63 |     - name: Discord
 64 |       title: Join the Python Docs Community Discord
 65 |       url: "https://discord.gg/nXkJ2JYvCu"
 66 |     - name: rss
 67 |       title: Get Updates by subscribing to our RSS Feed
 68 |       url: "./index.xml"
 69 | 
 70 | menu:
 71 |   main:
 72 |     - identifier: updates
 73 |       name: Monthly Updates
 74 |       url: /updates
 75 |       weight: 20
 76 |     - identifier: changelog
 77 |       name: Changelog
 78 |       url: /changelog
 79 |       weight: 30
 80 |     - identifier: archives
 81 |       name: Archives
 82 |       url: /archives
 83 |       weight: 40
 84 |     - identifier: search
 85 |       name: Search
 86 |       url: /search
 87 |       weight: 50
 88 |     - identifier: members
 89 |       name: Board Members
 90 |       url: /members
 91 |       weight: 60
 92 | 
 93 | module:
 94 |   hugoVersion:
 95 |     extended: true
 96 |     min: 0.110.0
 97 |   imports:
 98 |     - path: github.com/adityatelange/hugo-PaperMod
 99 |       disable: false
100 | 
101 | taxonomies:
102 |   category: categories
103 |   tag: tags
104 |   series: series
105 |   member: members
106 | 


--------------------------------------------------------------------------------
/layouts/_default/single.html:
--------------------------------------------------------------------------------
 1 | {{- define "main" }}
 2 | 
 3 | <article class="post-single">
 4 |   <header class="post-header">
 5 |     {{ partial "breadcrumbs.html" . }}
 6 |     <h1 class="post-title entry-hint-parent">
 7 |       {{ .Title }}
 8 |       {{- if .Draft }}
 9 |       <span class="entry-hint" title="Draft">
10 |         <svg xmlns="http://www.w3.org/2000/svg" height="35" viewBox="0 -960 960 960" fill="currentColor">
11 |           <path
12 |             d="M160-410v-60h300v60H160Zm0-165v-60h470v60H160Zm0-165v-60h470v60H160Zm360 580v-123l221-220q9-9 20-13t22-4q12 0 23 4.5t20 13.5l37 37q9 9 13 20t4 22q0 11-4.5 22.5T862.09-380L643-160H520Zm300-263-37-37 37 37ZM580-220h38l121-122-18-19-19-18-122 121v38Zm141-141-19-18 37 37-18-19Z" />
13 |         </svg>
14 |       </span>
15 |       {{- end }}
16 |     </h1>
17 |     {{- if .Description }}
18 |     <div class="post-description">
19 |       {{ .Description }}
20 |     </div>
21 |     {{- end }}
22 |     {{- if not (.Param "hideMeta") }}
23 |     <div class="post-meta">
24 |       {{- partial "post_meta.html" . -}}
25 |       {{- partial "translation_list.html" . -}}
26 |       {{- partial "edit_post.html" . -}}
27 |       {{- partial "post_canonical.html" . -}}
28 |     </div>
29 |     {{- end }}
30 |   </header>
31 |   {{- partial "members.html" . }}
32 | 
33 |   {{- $isHidden := (.Param "cover.hiddenInSingle") | default (.Param "cover.hidden") | default false }}
34 |   {{- partial "cover.html" (dict "cxt" . "IsSingle" true "isHidden" $isHidden) }}
35 |   {{- if (.Param "ShowToc") }}
36 |   {{- partial "toc.html" . }}
37 |   {{- end }}
38 | 
39 |   {{- if .Content }}
40 |   <div class="post-content">
41 |     {{- if not (.Param "disableAnchoredHeadings") }}
42 |     {{- partial "anchored_headings.html" .Content -}}
43 |     {{- else }}in content{{ .Content }}{{ end }}
44 |   </div>
45 |   {{- end }}
46 | 
47 |   <footer class="post-footer">
48 |     {{- $tags := .Language.Params.Taxonomies.tag | default "tags" }}
49 |     <ul class="post-tags">
50 |       {{- range ($.GetTerms $tags) }}
51 |       <li><a href="{{ .Permalink }}">{{ .LinkTitle }}</a></li>
52 |       {{- end }}
53 |     </ul>
54 |     {{- if (.Param "ShowPostNavLinks") }}
55 |     {{- partial "post_nav_links.html" . }}
56 |     {{- end }}
57 |     {{- if (and site.Params.ShowShareButtons (ne .Params.disableShare true)) }}
58 |     {{- partial "share_icons.html" . -}}
59 |     {{- end }}
60 |   </footer>
61 | 
62 |   {{- if (.Param "comments") }}
63 |   {{- partial "comments.html" . }}
64 |   {{- end }}
65 | </article>
66 | 
67 | {{- end }}{{/* end main */}}


--------------------------------------------------------------------------------
/layouts/changelog/list.html:
--------------------------------------------------------------------------------
  1 | {{- define "main" }}
  2 | 
  3 | {{- if (and site.Params.profileMode.enabled .IsHome) }}
  4 | {{- partial "index_profile.html" . }}
  5 | {{- else }} {{/* if not profileMode */}}
  6 | 
  7 | {{- if not .IsHome | and .Title }}
  8 | <header class="page-header">
  9 |   {{- partial "breadcrumbs.html" . }}
 10 |   <h1>
 11 |     {{ .Title }}
 12 |     {{- if and (or (eq .Kind `term`) (eq .Kind `section`)) (.Param "ShowRssButtonInSectionTermList") }}
 13 |     {{- with .OutputFormats.Get "rss" }}
 14 |     <a href="{{ .RelPermalink }}" title="RSS" aria-label="RSS">
 15 |       <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"
 16 |         stroke-linecap="round" stroke-linejoin="round" height="23">
 17 |         <path d="M4 11a9 9 0 0 1 9 9" />
 18 |         <path d="M4 4a16 16 0 0 1 16 16" />
 19 |         <circle cx="5" cy="19" r="1" />
 20 |       </svg>
 21 |     </a>
 22 |     {{- end }}
 23 |     {{- end }}
 24 |   </h1>
 25 |   {{- if .Description }}
 26 |   <div class="post-description">
 27 |     {{ .Description | markdownify }}
 28 |   </div>
 29 |   {{- end }}
 30 | </header>
 31 | {{- end }}
 32 | 
 33 | {{- if .Content }}
 34 | <div class="post-content">
 35 |   {{- if not (.Param "disableAnchoredHeadings") }}
 36 |   {{- partial "anchored_headings.html" .Content -}}
 37 |   {{- else }}{{ .Content }}{{ end }}
 38 | </div>
 39 | {{- end }}
 40 | 
 41 | {{- $pages := union .RegularPages .Sections }}
 42 | 
 43 | {{- if .IsHome }}
 44 | {{- $pages = where site.RegularPages "Type" "in" site.Params.mainSections }}
 45 | {{- $pages = where $pages "Params.hiddenInHomeList" "!=" "true"  }}
 46 | {{- end }}
 47 | 
 48 | {{- $paginator := .Paginate $pages }}
 49 | 
 50 | {{- if and .IsHome site.Params.homeInfoParams (eq $paginator.PageNumber 1) }}
 51 | {{- partial "home_info.html" . }}
 52 | {{- end }}
 53 | 
 54 | {{- $term := .Data.Term }}
 55 | {{- range $index, $page := $paginator.Pages }}
 56 | 
 57 | {{- $class := "post-entry" }}
 58 | 
 59 | {{- $user_preferred := or site.Params.disableSpecial1stPost site.Params.homeInfoParams }}
 60 | {{- if (and $.IsHome (eq $paginator.PageNumber 1) (eq $index 0) (not $user_preferred)) }}
 61 | {{- $class = "first-entry" }}
 62 | {{- else if $term }}
 63 | {{- $class = "post-entry tag-entry" }}
 64 | {{- end }}
 65 | 
 66 | <article class="{{ $class }}">
 67 |   {{- $isHidden := (.Param "cover.hiddenInList") | default (.Param "cover.hidden") | default false }}
 68 |   {{- partial "cover.html" (dict "cxt" . "IsSingle" false "isHidden" $isHidden) }}
 69 |   <header class="post-header">
 70 |     <h1 class="post-title entry-hint-parent">
 71 |       <a href="{{ .Permalink }}">{{ .Title }}</a>
 72 |       {{- if .Draft }}
 73 |       <span class="entry-hint" title="Draft">
 74 |         <svg xmlns="http://www.w3.org/2000/svg" height="35" viewBox="0 -960 960 960" fill="currentColor">
 75 |           <path
 76 |             d="M160-410v-60h300v60H160Zm0-165v-60h470v60H160Zm0-165v-60h470v60H160Zm360 580v-123l221-220q9-9 20-13t22-4q12 0 23 4.5t20 13.5l37 37q9 9 13 20t4 22q0 11-4.5 22.5T862.09-380L643-160H520Zm300-263-37-37 37 37ZM580-220h38l121-122-18-19-19-18-122 121v38Zm141-141-19-18 37 37-18-19Z" />
 77 |         </svg>
 78 |       </span>
 79 |       {{- end }}
 80 |     </h1>
 81 |     {{- if .Description }}
 82 |     <div class="post-description">
 83 |       {{ .Description }}
 84 |     </div>
 85 |     {{- end }}
 86 |     {{- if not (.Param "hideMeta") }}
 87 |     <div class="post-meta">
 88 |       {{- partial "post_meta.html" . -}}
 89 |       {{- partial "translation_list.html" . -}}
 90 |       {{- partial "edit_post.html" . -}}
 91 |       {{- partial "post_canonical.html" . -}}
 92 |     </div>
 93 |     {{- end }}
 94 |   </header>
 95 |   {{- partial "members.html" . }}
 96 | 
 97 |   {{- $isHidden := (.Param "cover.hiddenInSingle") | default (.Param "cover.hidden") | default false }}
 98 |   {{- partial "cover.html" (dict "cxt" . "IsSingle" true "isHidden" $isHidden) }}
 99 |   {{- if (.Param "ShowToc") }}
100 |   {{- partial "toc.html" . }}
101 |   {{- end }}
102 | 
103 |   {{- if .Content }}
104 |   <div class="post-content">
105 |     {{- if not (.Param "disableAnchoredHeadings") }}
106 |     {{- partial "anchored_headings.html" .Content -}}
107 |     {{- else }}in content{{ .Content }}{{ end }}
108 |   </div>
109 |   {{- end }}
110 | 
111 |   <footer class="post-footer">
112 |     {{- $tags := .Language.Params.Taxonomies.tag | default "tags" }}
113 |     <ul class="post-tags">
114 |       {{- range ($.GetTerms $tags) }}
115 |       <li><a href="{{ .Permalink }}">{{ .LinkTitle }}</a></li>
116 |       {{- end }}
117 |     </ul>
118 |     {{- if (.Param "ShowPostNavLinks") }}
119 |     {{- partial "post_nav_links.html" . }}
120 |     {{- end }}
121 |   </footer>
122 | 
123 |   {{- if (.Param "comments") }}
124 |   {{- partial "comments.html" . }}
125 |   {{- end }}
126 | </article>
127 | {{- end }}
128 | 
129 | {{- if gt $paginator.TotalPages 1 }}
130 | <footer class="page-footer">
131 |   <nav class="pagination">
132 |     {{- if $paginator.HasPrev }}
133 |     <a class="prev" href="{{ $paginator.Prev.URL | absURL }}">
134 |       «&nbsp;{{ i18n "prev_page" }}&nbsp;
135 |       {{- if (.Param "ShowPageNums") }}
136 |       {{- sub $paginator.PageNumber 1 }}/{{ $paginator.TotalPages }}
137 |       {{- end }}
138 |     </a>
139 |     {{- end }}
140 |     {{- if $paginator.HasNext }}
141 |     <a class="next" href="{{ $paginator.Next.URL | absURL }}">
142 |       {{- i18n "next_page" }}&nbsp;
143 |       {{- if (.Param "ShowPageNums") }}
144 |       {{- add 1 $paginator.PageNumber }}/{{ $paginator.TotalPages }}
145 |       {{- end }}&nbsp;»
146 |     </a>
147 |     {{- end }}
148 |   </nav>
149 | </footer>
150 | {{- end }}
151 | 
152 | {{- end }}{{/* end profileMode */}}
153 | 
154 | {{- end }}{{- /* end main */ -}}


--------------------------------------------------------------------------------
/layouts/partials/members.html:
--------------------------------------------------------------------------------
 1 | <div class="post-content" id="members">
 2 |     {{if $.Param "members" }}
 3 |         <h3 id="attendees">Attendees</h3>
 4 |         <ul>
 5 |             {{ range $member := .Param "members" }}
 6 |             <li>
 7 |                 <a href="{{ `members/` | relLangURL }}{{ $member | urlize }}/">
 8 |                 {{ $member }}
 9 |             </a>
10 |             </li>
11 |             {{ end }}
12 |             {{ range $guest := .Param "guests" }}
13 |             <li>
14 |                 {{ $guest}}
15 |             </li>
16 |             {{ end }}
17 |         </ul>
18 |     {{ end }}
19 | </div>


--------------------------------------------------------------------------------
/netlify.toml:
--------------------------------------------------------------------------------
 1 | [build]
 2 |   publish = "public"
 3 |   command = "hugo --gc --minify"
 4 | 
 5 |   [build.environment]
 6 |     HUGO_VERSION = "0.128.0"
 7 | 
 8 | [context.production.environment]
 9 |   HUGO_ENV           = "production"
10 |   HUGO_ENABLEGITINFO = "true"
11 | 
12 | [context.split1]
13 |   command = "hugo --gc --minify --enableGitInfo"
14 | 
15 |   [context.split1.environment]
16 |     HUGO_ENV = "production"
17 | 
18 | [context.deploy-preview]
19 |   command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL"
20 | 
21 | [context.branch-deploy]
22 |   command = "hugo --gc --minify -b $DEPLOY_PRIME_URL"
23 | 
24 | [context.next.environment]
25 |   HUGO_ENABLEGITINFO = "true"
26 | 
27 | [[redirects]]
28 |   from   = "/npmjs/*"
29 |   to     = "/npmjs/"
30 |   status = 200
31 | 


--------------------------------------------------------------------------------