sphinx-github-changelog 2.1.1__tar.gz → 2.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/PKG-INFO +24 -10
  2. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/README.rst +23 -9
  3. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/sphinx_github_changelog/changelog.py +9 -4
  4. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/sphinx_github_changelog/config.py +17 -2
  5. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/sphinx_github_changelog/github_releases.py +9 -2
  6. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/sphinx_github_changelog/setup.py +2 -4
  7. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/tests/acceptance/test_all.py +1 -0
  8. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/tests/conftest.py +1 -0
  9. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/tests/unit/test_changelog.py +27 -0
  10. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/.editorconfig +0 -0
  11. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/.github/CODEOWNERS +0 -0
  12. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/.github/PULL_REQUEST_TEMPLATE.md +0 -0
  13. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/.github/release.yml +0 -0
  14. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/.github/renovate.json5 +0 -0
  15. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/.github/workflows/autofix.yml +0 -0
  16. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/.github/workflows/ci.yml +0 -0
  17. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/.github/workflows/coverage-comment.yml +0 -0
  18. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/.gitignore +0 -0
  19. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/.pre-commit-config.yaml +0 -0
  20. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/.readthedocs.yml +0 -0
  21. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/CHANGELOG.rst +0 -0
  22. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/CODE_OF_CONDUCT.rst +0 -0
  23. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/CONTRIBUTING.rst +0 -0
  24. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/LICENSE +0 -0
  25. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/docs/Makefile +0 -0
  26. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/docs/conduct.rst +0 -0
  27. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/docs/conf.py +0 -0
  28. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/docs/contributing.rst +0 -0
  29. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/docs/index.rst +0 -0
  30. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/pyproject.toml +0 -0
  31. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/scripts/README.md +0 -0
  32. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/scripts/docs +0 -0
  33. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/scripts/lint +0 -0
  34. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/scripts/tests +0 -0
  35. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/sphinx_github_changelog/__init__.py +0 -0
  36. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/sphinx_github_changelog/credentials.py +0 -0
  37. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/sphinx_github_changelog/exceptions.py +0 -0
  38. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/sphinx_github_changelog/urls.py +0 -0
  39. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/tests/__init__.py +0 -0
  40. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/tests/acceptance/__init__.py +0 -0
  41. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/tests/acceptance/changelog.html +0 -0
  42. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/tests/roots/test-all/conf.py +0 -0
  43. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/tests/roots/test-all/index.rst +0 -0
  44. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/tests/roots/test-error/conf.py +0 -0
  45. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/tests/roots/test-error/index.rst +0 -0
  46. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/tests/unit/__init__.py +0 -0
  47. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/tests/unit/test_git.py +0 -0
  48. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/tests/unit/test_github_releases.py +0 -0
  49. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/tests/unit/test_urls.py +0 -0
  50. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.2.0}/uv.lock +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: sphinx-github-changelog
3
- Version: 2.1.1
3
+ Version: 2.2.0
4
4
  Summary: Build a sphinx changelog from GitHub Releases
5
5
  Project-URL: Homepage, https://sphinx-github-changelog.readthedocs.io/en/latest/
6
6
  Project-URL: Repository, https://github.com/ewjoachim/sphinx-github-changelog
@@ -205,15 +205,29 @@ environment variable. You can also set the token as ``sphinx_github_changelog_to
205
205
  Extension options (``conf.py``)
206
206
  -------------------------------
207
207
 
208
- - ``sphinx_github_changelog_token`` (optional): GitHub API token, if needed, see above
209
- (please do **NOT** commit your secrets).
210
-
211
- The following options are useful in some cases, though most of the time, the
212
- corresponding values will be detected automatically from the ``:github:`` parameter
213
- passed to the directive:
214
-
215
- - ``sphinx_github_changelog_root_repo`` (optional): Root URL to the repository.
216
- - ``sphinx_github_changelog_graphql_url`` (optional): URL to GraphQL API.
208
+ All options can also be set via environment variables of the same name in uppercase
209
+ (e.g. ``SPHINX_GITHUB_CHANGELOG_TOKEN``).
210
+
211
+ .. list-table::
212
+ :header-rows: 1
213
+ :widths: 30 10 60
214
+
215
+ * - Option
216
+ - Default
217
+ - Description
218
+ * - ``sphinx_github_changelog_token``
219
+ - ``None``
220
+ - GitHub API token. See above (please do **NOT** commit your secrets).
221
+ * - ``sphinx_github_changelog_root_repo``
222
+ - ``None``
223
+ - Root URL to the repository. Usually detected automatically.
224
+ * - ``sphinx_github_changelog_graphql_url``
225
+ - ``None``
226
+ - URL to GraphQL API. Usually detected automatically.
227
+ * - ``sphinx_github_changelog_include_prereleases``
228
+ - ``True``
229
+ - Whether to include pre-releases in the changelog. Set to ``False``
230
+ to exclude them (env var accepts ``0``, ``false``, ``no``).
217
231
 
218
232
  .. _ReadTheDocs: https://readthedocs.org/
219
233
 
@@ -178,15 +178,29 @@ environment variable. You can also set the token as ``sphinx_github_changelog_to
178
178
  Extension options (``conf.py``)
179
179
  -------------------------------
180
180
 
181
- - ``sphinx_github_changelog_token`` (optional): GitHub API token, if needed, see above
182
- (please do **NOT** commit your secrets).
183
-
184
- The following options are useful in some cases, though most of the time, the
185
- corresponding values will be detected automatically from the ``:github:`` parameter
186
- passed to the directive:
187
-
188
- - ``sphinx_github_changelog_root_repo`` (optional): Root URL to the repository.
189
- - ``sphinx_github_changelog_graphql_url`` (optional): URL to GraphQL API.
181
+ All options can also be set via environment variables of the same name in uppercase
182
+ (e.g. ``SPHINX_GITHUB_CHANGELOG_TOKEN``).
183
+
184
+ .. list-table::
185
+ :header-rows: 1
186
+ :widths: 30 10 60
187
+
188
+ * - Option
189
+ - Default
190
+ - Description
191
+ * - ``sphinx_github_changelog_token``
192
+ - ``None``
193
+ - GitHub API token. See above (please do **NOT** commit your secrets).
194
+ * - ``sphinx_github_changelog_root_repo``
195
+ - ``None``
196
+ - Root URL to the repository. Usually detected automatically.
197
+ * - ``sphinx_github_changelog_graphql_url``
198
+ - ``None``
199
+ - URL to GraphQL API. Usually detected automatically.
200
+ * - ``sphinx_github_changelog_include_prereleases``
201
+ - ``True``
202
+ - Whether to include pre-releases in the changelog. Set to ``False``
203
+ to exclude them (env var accepts ``0``, ``false``, ``no``).
190
204
 
191
205
  .. _ReadTheDocs: https://readthedocs.org/
192
206
 
@@ -64,6 +64,9 @@ def compute_changelog(
64
64
 
65
65
  pypi_name = extract_pypi_package_name(url=options.pypi)
66
66
 
67
+ if not config.include_prereleases:
68
+ releases = [r for r in releases if not r.is_prerelease]
69
+
67
70
  result_nodes = (
68
71
  node_for_release(release=release, pypi_name=pypi_name) for release in releases
69
72
  )
@@ -113,9 +116,10 @@ def extract_pypi_package_name(url: str | None) -> str | None:
113
116
 
114
117
 
115
118
  def get_release_title(title: str | None, tag: str):
119
+ version = tag.removeprefix("v")
116
120
  if not title:
117
- return tag
118
- return title if tag in title else f"{tag}: {title}"
121
+ return version
122
+ return title if version in title else f"{version}: {title}"
119
123
 
120
124
 
121
125
  def node_for_release(
@@ -126,12 +130,13 @@ def node_for_release(
126
130
  return None # For now, draft releases are excluded
127
131
 
128
132
  tag = release.tag_name
133
+ version = tag.removeprefix("v")
129
134
  title = release.name
130
135
  date = release.published_at.isoformat()
131
136
  title = get_release_title(title=title, tag=tag)
132
137
 
133
138
  # Section
134
- id_section = nodes.make_id("release-" + tag)
139
+ id_section = nodes.make_id("release-" + version)
135
140
  section = nodes.section(ids=[id_section])
136
141
 
137
142
  section += nodes.title(text=title)
@@ -143,7 +148,7 @@ def node_for_release(
143
148
  subtitle += nodes.reference("", "GitHub", refuri=release.url)
144
149
  if pypi_name:
145
150
  subtitle += nodes.Text(" - ")
146
- url = f"https://pypi.org/project/{pypi_name}/{tag}/"
151
+ url = f"https://pypi.org/project/{pypi_name}/{version}/"
147
152
  subtitle += nodes.reference("", "PyPI", refuri=url)
148
153
 
149
154
  subtitle_paragraph = nodes.paragraph()
@@ -1,6 +1,8 @@
1
1
  from __future__ import annotations
2
2
 
3
3
  import dataclasses
4
+ import os
5
+ from collections.abc import Iterator
4
6
  from typing import Any, ClassVar
5
7
 
6
8
 
@@ -24,12 +26,24 @@ class ChangelogConfig:
24
26
  token: str | None = None
25
27
  root_repo: str | None = None
26
28
  graphql_url: str | None = None
29
+ include_prereleases: bool = True
27
30
 
28
31
  prefix: ClassVar[str] = "sphinx_github_changelog"
29
32
 
30
33
  @classmethod
31
- def get_field_names(cls) -> list[str]:
32
- return [f.name for f in dataclasses.fields(cls)]
34
+ def get_config_defaults(cls) -> Iterator[tuple[str, str | bool | None]]:
35
+ for field in dataclasses.fields(cls):
36
+ option_name = f"{cls.prefix}_{field.name}"
37
+ env_value = os.environ.get(option_name.upper())
38
+ if field.type == "bool":
39
+ default: str | bool | None = (
40
+ env_value.lower() not in ("0", "false", "no")
41
+ if env_value
42
+ else bool(field.default)
43
+ )
44
+ else:
45
+ default = env_value
46
+ yield option_name, default
33
47
 
34
48
  @classmethod
35
49
  def from_sphinx_env_config(cls, sphinx_config: Any):
@@ -37,4 +51,5 @@ class ChangelogConfig:
37
51
  token=sphinx_config.sphinx_github_changelog_token,
38
52
  root_repo=sphinx_config.sphinx_github_changelog_root_repo,
39
53
  graphql_url=sphinx_config.sphinx_github_changelog_graphql_url,
54
+ include_prereleases=sphinx_config.sphinx_github_changelog_include_prereleases,
40
55
  )
@@ -17,6 +17,7 @@ class Release:
17
17
  tag_name: str
18
18
  published_at: datetime.date
19
19
  is_draft: bool
20
+ is_prerelease: bool
20
21
 
21
22
  @classmethod
22
23
  def from_graphql(cls, data: dict) -> Release:
@@ -27,6 +28,7 @@ class Release:
27
28
  tag_name=data["tagName"],
28
29
  published_at=datetime.date.fromisoformat(data["publishedAt"][:10]),
29
30
  is_draft=data["isDraft"],
31
+ is_prerelease=data["isPrerelease"],
30
32
  )
31
33
 
32
34
 
@@ -40,7 +42,7 @@ def extract_releases(
40
42
  repository(owner: $owner, name: $repo) {
41
43
  releases(orderBy: {field: CREATED_AT, direction: DESC}, first:100) {
42
44
  nodes {
43
- name, description, url, tagName, publishedAt, isDraft
45
+ name, description, url, tagName, publishedAt, isDraft, isPrerelease
44
46
  }
45
47
  }
46
48
  }
@@ -54,8 +56,13 @@ def extract_releases(
54
56
  result = github_call(url=url, payload=payload, token=token)
55
57
  try:
56
58
  releases = result["data"]["repository"]["releases"]["nodes"]
59
+ # Sort by publication date descending (API only supports CREATED_AT ordering)
57
60
  # If you don't have the right to see draft releases, they're "None"
58
- return [Release.from_graphql(r) for r in releases if r]
61
+ return sorted(
62
+ (Release.from_graphql(r) for r in releases if r),
63
+ key=lambda r: r.published_at,
64
+ reverse=True,
65
+ )
59
66
  except (KeyError, TypeError):
60
67
  raise exceptions.GitHubAPIError(
61
68
  f"GitHub API error unexpected format:\n{result!r}"
@@ -1,7 +1,6 @@
1
1
  from __future__ import annotations
2
2
 
3
3
  import importlib.metadata
4
- import os
5
4
 
6
5
  from . import changelog, config
7
6
 
@@ -11,11 +10,10 @@ def version() -> str:
11
10
 
12
11
 
13
12
  def setup(app):
14
- for name in config.ChangelogConfig.get_field_names():
15
- option_name = f"{config.ChangelogConfig.prefix}_{name}"
13
+ for option_name, default in config.ChangelogConfig.get_config_defaults():
16
14
  app.add_config_value(
17
15
  name=option_name,
18
- default=os.environ.get(option_name.upper()),
16
+ default=default,
19
17
  rebuild="html",
20
18
  )
21
19
 
@@ -79,6 +79,7 @@ Let's rename \*our-new-project\* to \*our-old-project\*.
79
79
  "tagName": "1.0.0",
80
80
  "publishedAt": "2000-01-01",
81
81
  "isDraft": False,
82
+ "isPrerelease": False,
82
83
  }
83
84
 
84
85
 
@@ -24,6 +24,7 @@ def release_dict():
24
24
  "tagName": "1.0.0",
25
25
  "publishedAt": "2000-01-01",
26
26
  "isDraft": False,
27
+ "isPrerelease": False,
27
28
  }
28
29
 
29
30
 
@@ -78,6 +78,30 @@ def test_compute_changelog_token(extract_releases):
78
78
  assert "1.0.0: A new hope" in node_to_string(nodes[0])
79
79
 
80
80
 
81
+ def test_compute_changelog_exclude_prereleases(mocker, release):
82
+ release.is_prerelease = True
83
+ mocker.patch(
84
+ "sphinx_github_changelog.github_releases.extract_releases",
85
+ return_value=[release],
86
+ )
87
+ options = config_module.ChangelogDirectiveOptions(
88
+ github="https://github.com/a/b/releases",
89
+ )
90
+ config = config_module.ChangelogConfig(token="token", include_prereleases=False)
91
+ nodes = changelog.compute_changelog(options=options, config=config)
92
+ assert nodes == []
93
+
94
+
95
+ def test_compute_changelog_include_prereleases(extract_releases, release):
96
+ release.is_prerelease = True
97
+ options = config_module.ChangelogDirectiveOptions(
98
+ github="https://github.com/a/b/releases",
99
+ )
100
+ config = config_module.ChangelogConfig(token="token", include_prereleases=True)
101
+ nodes = changelog.compute_changelog(options=options, config=config)
102
+ assert "1.0.0: A new hope" in node_to_string(nodes[0])
103
+
104
+
81
105
  def test_no_token_no_url():
82
106
  assert node_to_string(changelog.no_token(changelog_url=None)) == canonicalize(
83
107
  """
@@ -198,6 +222,9 @@ def test_node_for_release_draft(release):
198
222
  ("1.0.0: Foo", "1.0.0", "1.0.0: Foo"),
199
223
  ("Fix 1.0.0", "1.0.1", "1.0.1: Fix 1.0.0"),
200
224
  (None, "1.0.0", "1.0.0"),
225
+ ("Foo", "v1.0.0", "1.0.0: Foo"),
226
+ ("1.0.0: Foo", "v1.0.0", "1.0.0: Foo"),
227
+ (None, "v1.0.0", "1.0.0"),
201
228
  ],
202
229
  )
203
230
  def test_get_release_title(title, tag, expected):