Skip to content

Commit 4511c47

Browse files
MariattanedbatAA-Turner
authored
Update the changelog (#28)
Summarize the decisions. Note: Removed the "Changelog.md" file and moved the remaining entry into `/content/changelog` Add brief summary of each decisions. --------- Co-authored-by: Ned Batchelder <ned@nedbatchelder.com> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
1 parent e6516d5 commit 4511c47

11 files changed

+298
-26
lines changed

‎CHANGELOG.md‎

Lines changed: 0 additions & 7 deletions
This file was deleted.

‎content/changelog/2024-07-12-function-signatures.md‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
author: ["Ned Batchelder"]
3-
title: "Changelog: July 12, 2024"
3+
title: "Function signatures include slash and star"
44
date: "2024-07-12"
55
tags: ["changelog"]
66
categories: ["changelog"]
@@ -10,3 +10,17 @@ TocOpen: false
1010
---
1111

1212
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).

‎content/changelog/2024-07-18-clarify-timezone.md‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
author: ["Ned Batchelder"]
3-
title: "Changelog: July 18, 2024"
3+
title: "Timezone vs time zone"
44
date: "2024-07-18"
55
tags: ["changelog"]
66
categories: ["changelog"]
@@ -10,3 +10,18 @@ TocOpen: false
1010
---
1111

1212
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+

‎content/changelog/2024-08-28-style-guide-recs.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
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‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
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‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
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‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
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+

‎content/changelog/_index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
title: "Editorial Board Decisions"
3+
layout: "changelog"
34
---
45

56
Editorial Board Decisions

‎hugo.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ baseURL: "https://python.github.io/editorial-board/"
22
title: Python Docs Editorial Board
33
copyright: "© [Python Docs Editorial Board and Contributors](https://github.com/python/editorial-board/graphs/contributors)"
44
pagination:
5-
pagerSize: 5
5+
pagerSize: 10
66

77
enableInlineShortcodes: true
88
enableRobotsTXT: true
@@ -31,7 +31,7 @@ params:
3131
defaultTheme: auto
3232
# disableThemeToggle: true
3333
ShowShareButtons: true
34-
ShowReadingTime: true
34+
ShowReadingTime: false
3535
# disableSpecial1stPost: true
3636
displayFullLangName: true
3737
ShowPostNavLinks: true

‎layouts/changelog/list.html‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
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 */ -}}

0 commit comments

Comments
 (0)