sphinx-github-changelog 2.1.1__tar.gz → 2.3.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 (61) hide show
  1. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/.github/renovate.json5 +1 -0
  2. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/.github/workflows/ci.yml +9 -1
  3. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/.pre-commit-config.yaml +1 -0
  4. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/CONTRIBUTING.rst +29 -2
  5. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/PKG-INFO +39 -20
  6. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/README.rst +37 -19
  7. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/pyproject.toml +4 -1
  8. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/sphinx_github_changelog/changelog.py +26 -13
  9. sphinx_github_changelog-2.3.0/sphinx_github_changelog/config.py +64 -0
  10. sphinx_github_changelog-2.3.0/sphinx_github_changelog/github_releases.py +144 -0
  11. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/sphinx_github_changelog/setup.py +2 -4
  12. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/sphinx_github_changelog/urls.py +8 -4
  13. sphinx_github_changelog-2.3.0/tests/acceptance/cassettes/test_all/test_build.yaml +176 -0
  14. sphinx_github_changelog-2.3.0/tests/acceptance/cassettes/test_all/test_build_404.yaml +69 -0
  15. sphinx_github_changelog-2.3.0/tests/acceptance/changelog.html +272 -0
  16. sphinx_github_changelog-2.3.0/tests/acceptance/test_all.py +61 -0
  17. sphinx_github_changelog-2.3.0/tests/conftest.py +103 -0
  18. {sphinx_github_changelog-2.1.1/tests/roots/test-error → sphinx_github_changelog-2.3.0/tests/roots/test-404}/conf.py +0 -2
  19. sphinx_github_changelog-2.3.0/tests/roots/test-404/index.rst +4 -0
  20. sphinx_github_changelog-2.3.0/tests/roots/test-all/conf.py +5 -0
  21. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/tests/roots/test-all/index.rst +1 -1
  22. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/tests/unit/test_changelog.py +48 -4
  23. sphinx_github_changelog-2.3.0/tests/unit/test_config.py +40 -0
  24. sphinx_github_changelog-2.3.0/tests/unit/test_github_releases.py +236 -0
  25. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/tests/unit/test_urls.py +9 -4
  26. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/uv.lock +171 -0
  27. sphinx_github_changelog-2.1.1/sphinx_github_changelog/config.py +0 -40
  28. sphinx_github_changelog-2.1.1/sphinx_github_changelog/github_releases.py +0 -88
  29. sphinx_github_changelog-2.1.1/tests/acceptance/changelog.html +0 -71
  30. sphinx_github_changelog-2.1.1/tests/acceptance/test_all.py +0 -108
  31. sphinx_github_changelog-2.1.1/tests/conftest.py +0 -53
  32. sphinx_github_changelog-2.1.1/tests/unit/test_github_releases.py +0 -115
  33. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/.editorconfig +0 -0
  34. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/.github/CODEOWNERS +0 -0
  35. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/.github/PULL_REQUEST_TEMPLATE.md +0 -0
  36. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/.github/release.yml +0 -0
  37. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/.github/workflows/autofix.yml +0 -0
  38. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/.github/workflows/coverage-comment.yml +0 -0
  39. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/.gitignore +0 -0
  40. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/.readthedocs.yml +0 -0
  41. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/CHANGELOG.rst +0 -0
  42. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/CODE_OF_CONDUCT.rst +0 -0
  43. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/LICENSE +0 -0
  44. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/docs/Makefile +0 -0
  45. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/docs/conduct.rst +0 -0
  46. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/docs/conf.py +0 -0
  47. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/docs/contributing.rst +0 -0
  48. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/docs/index.rst +0 -0
  49. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/scripts/README.md +0 -0
  50. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/scripts/docs +0 -0
  51. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/scripts/lint +0 -0
  52. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/scripts/tests +0 -0
  53. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/sphinx_github_changelog/__init__.py +0 -0
  54. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/sphinx_github_changelog/credentials.py +0 -0
  55. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/sphinx_github_changelog/exceptions.py +0 -0
  56. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/tests/__init__.py +0 -0
  57. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/tests/acceptance/__init__.py +0 -0
  58. {sphinx_github_changelog-2.1.1/tests/roots/test-all → sphinx_github_changelog-2.3.0/tests/roots/test-error}/conf.py +0 -0
  59. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/tests/roots/test-error/index.rst +0 -0
  60. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/tests/unit/__init__.py +0 -0
  61. {sphinx_github_changelog-2.1.1 → sphinx_github_changelog-2.3.0}/tests/unit/test_git.py +0 -0
@@ -2,6 +2,7 @@
2
2
  extends: ["config:recommended", ":enablePreCommit"],
3
3
  schedule: ["before 4am on Saturday"],
4
4
  labels: ["PR type: dependencies 🤖"],
5
+ minimumReleaseAge: "5 days",
5
6
  lockFileMaintenance: {
6
7
  enabled: true,
7
8
  automerge: true,
@@ -31,6 +31,8 @@ jobs:
31
31
 
32
32
  - name: Run prek
33
33
  uses: j178/prek-action@bdca6f102f98e2b4c7029491a53dfd366469e33d # v2.0.4
34
+ env:
35
+ PREK_SKIP: no-commit-to-branch
34
36
 
35
37
  tests:
36
38
  strategy:
@@ -81,10 +83,13 @@ jobs:
81
83
  pattern: coverage-*
82
84
  merge-multiple: true
83
85
 
86
+ - name: Prepare merged coverage data
87
+ run: |
88
+ pipx run coverage combine
89
+
84
90
  - name: Display coverage
85
91
  uses: ewjoachim/python-coverage-comment-action@63f52f4fbbffada6e8dee8ec432de7e01df9ba79 # v3.41
86
92
  with:
87
- MERGE_COVERAGE_FILES: true
88
93
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
89
94
 
90
95
  - name: Store Pull Request comment to be posted
@@ -93,6 +98,9 @@ jobs:
93
98
  name: python-coverage-comment-action
94
99
  path: python-coverage-comment-action.txt
95
100
 
101
+ - name: Enforce coverage >= 100%
102
+ run: pipx run coverage report --fail-under=100
103
+
96
104
  publish:
97
105
  name: Publish package to PyPI
98
106
  if: github.event_name == 'push' && github.ref_type == 'tag'
@@ -23,6 +23,7 @@ repos:
23
23
  - id: end-of-file-fixer
24
24
  - id: trailing-whitespace
25
25
  - id: mixed-line-ending
26
+ - id: no-commit-to-branch
26
27
 
27
28
  - repo: https://github.com/astral-sh/ruff-pre-commit
28
29
  rev: v0.15.14
@@ -29,7 +29,10 @@ I want a venv to play locally
29
29
 
30
30
  $ uv sync
31
31
 
32
- Use at ``uv sync --python=3.x`` if you want to work on a specific Python version.
32
+ Use ``uv sync --python=3.x`` if you want to work on a specific Python version.
33
+
34
+ There is no need to activate ``.venv`` manually. Run project commands through
35
+ ``uv run`` instead.
33
36
 
34
37
  I want to run the tests
35
38
  ---------------------------
@@ -40,6 +43,30 @@ The easiest way to run the tests on a single python version is:
40
43
 
41
44
  $ uv run pytest
42
45
 
46
+ Coverage is enforced at 100% on merged matrix coverage in CI. Branches gated by
47
+ Python-version checks do not need to be covered in every local test run, as long as
48
+ they are covered by at least one CI matrix job. When you run pytest locally, you'll get
49
+ a terminal report at the bottom as well as a more detailed HTML report in
50
+ ``htmlcov/index.html``. In PRs, a summary of the coverage report is posted as a comment
51
+ by the CI.
52
+
53
+ Acceptance tests and fixtures
54
+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
55
+
56
+ Acceptance tests in ``tests/acceptance/`` are snapshot-like tests of
57
+ the built HTML.
58
+
59
+ If the normalized HTML output changes, ``tests/acceptance/changelog.html`` is
60
+ rewritten by the test before it fails. Review the updated fixture, then run the
61
+ test again and commit the fixture change if it is expected.
62
+
63
+ Those tests also use VCR cassettes from ``tests/acceptance/cassettes``.
64
+ If the GitHub API fixture data needs to be refreshed, use:
65
+
66
+ .. code-block:: console
67
+
68
+ # Re-record interactions in the selected test run
69
+ $ uv run pytest --record-mode=rewrite
43
70
 
44
71
  I want to build the documentation
45
72
  ---------------------------------
@@ -49,7 +76,7 @@ Build with:
49
76
  .. code-block:: console
50
77
 
51
78
  $ scripts/docs
52
- $ python -m webbrowser docs/_build/html/index.html
79
+ $ uv run python -m webbrowser docs/_build/html/index.html
53
80
 
54
81
  If Sphinx's console output is localized, and you would rather have it in English,
55
82
  use the environment variable ``export LC_ALL=C.utf-8``.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: sphinx-github-changelog
3
- Version: 2.1.1
3
+ Version: 2.3.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
@@ -23,6 +23,7 @@ Requires-Dist: docutils
23
23
  Requires-Dist: httpx
24
24
  Requires-Dist: myst-parser>=5.1.0
25
25
  Requires-Dist: sphinx
26
+ Requires-Dist: tenacity
26
27
  Description-Content-Type: text/x-rst
27
28
 
28
29
  Sphinx Github Changelog: Build a sphinx changelog from GitHub Releases
@@ -154,7 +155,7 @@ git remotes in this order:
154
155
  1. ``upstream`` remote
155
156
  2. ``origin`` remote
156
157
 
157
- The GraphQL API and GitHub root URL are derived from this URL.
158
+ The GitHub API base URL and GitHub root URL are derived from this URL.
158
159
 
159
160
  If for any reason, you'd rather provide the repository explicitly (e.g. the doc
160
161
  repo doesn't match the repo you're releasing from, or anything else), you can
@@ -165,8 +166,13 @@ details.
165
166
  Authentication
166
167
  --------------
167
168
 
168
- The extension uses the GitHub GraphQL API to retrieve the changelog. This
169
- requires authentication using a GitHub API token.
169
+ The extension uses the GitHub Releases REST API to retrieve the changelog.
170
+
171
+ For public repositories, this can usually work without authentication, though it's not
172
+ recommended as GitHub applies IP-based rate limits, so this may make your builds flaky.
173
+ Note that there will be automatic retries after HTTP 429 responses, controlled by the
174
+ ``sphinx_github_changelog_retries`` option (see below). For private repositories (or
175
+ when unauthenticated requests are rate limited), you need a GitHub API token.
170
176
 
171
177
  Tokens can be read from (in this order):
172
178
 
@@ -189,13 +195,12 @@ variable:
189
195
  env:
190
196
  SPHINX_GITHUB_CHANGELOG_TOKEN: ${{ github.token }}
191
197
 
192
- If you're not in one of the cases above (e.g. for ReadTheDocs, at least for the `time
193
- being`__), you'll need a personal access token. If the repository is public, the token
194
- doesn't need any special access (you can uncheck everything). For private and internal
195
- repositories, the token must have ``repo`` scope (classic tokens) or ``contents: read``
196
- access (fine-grained tokens).
197
-
198
- .. __: https://github.com/readthedocs/readthedocs.org/issues/13053
198
+ If you're not in one of the cases above and your build environment cannot use
199
+ anonymous API access reliably (e.g. rate limits), you'll need a personal access
200
+ token. If the repository is public, the token doesn't need any special access
201
+ (you can uncheck everything). For private and internal repositories, the token
202
+ must have ``repo`` scope (classic tokens) or ``contents: read`` access
203
+ (fine-grained tokens).
199
204
 
200
205
  Pass the token as the ``SPHINX_GITHUB_CHANGELOG_TOKEN`` (or ``GITHUB_TOKEN``)
201
206
  environment variable. You can also set the token as ``sphinx_github_changelog_token`` in
@@ -205,15 +210,29 @@ environment variable. You can also set the token as ``sphinx_github_changelog_to
205
210
  Extension options (``conf.py``)
206
211
  -------------------------------
207
212
 
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.
213
+ All options can also be set via environment variables of the same name in uppercase
214
+ (e.g. ``SPHINX_GITHUB_CHANGELOG_TOKEN``).
215
+
216
+ .. list-table::
217
+ :header-rows: 1
218
+ :widths: 30 10 60
219
+
220
+ * - Option
221
+ - Default
222
+ - Description
223
+ * - ``sphinx_github_changelog_token``
224
+ - ``None``
225
+ - GitHub API token. See above (please do **NOT** commit your secrets).
226
+ * - ``sphinx_github_changelog_root_repo``
227
+ - ``None``
228
+ - Root URL to the repository. Usually detected automatically.
229
+ * - ``sphinx_github_changelog_include_prereleases``
230
+ - ``True``
231
+ - Whether to include pre-releases in the changelog. Set to ``False``
232
+ to exclude them (env var accepts ``0``, ``false``, ``no``).
233
+ * - ``sphinx_github_changelog_retries``
234
+ - ``3``
235
+ - Number of retries after HTTP 429 responses from GitHub API. Will wait exponentially longer between each retry, starting at 5 second.
217
236
 
218
237
  .. _ReadTheDocs: https://readthedocs.org/
219
238
 
@@ -127,7 +127,7 @@ git remotes in this order:
127
127
  1. ``upstream`` remote
128
128
  2. ``origin`` remote
129
129
 
130
- The GraphQL API and GitHub root URL are derived from this URL.
130
+ The GitHub API base URL and GitHub root URL are derived from this URL.
131
131
 
132
132
  If for any reason, you'd rather provide the repository explicitly (e.g. the doc
133
133
  repo doesn't match the repo you're releasing from, or anything else), you can
@@ -138,8 +138,13 @@ details.
138
138
  Authentication
139
139
  --------------
140
140
 
141
- The extension uses the GitHub GraphQL API to retrieve the changelog. This
142
- requires authentication using a GitHub API token.
141
+ The extension uses the GitHub Releases REST API to retrieve the changelog.
142
+
143
+ For public repositories, this can usually work without authentication, though it's not
144
+ recommended as GitHub applies IP-based rate limits, so this may make your builds flaky.
145
+ Note that there will be automatic retries after HTTP 429 responses, controlled by the
146
+ ``sphinx_github_changelog_retries`` option (see below). For private repositories (or
147
+ when unauthenticated requests are rate limited), you need a GitHub API token.
143
148
 
144
149
  Tokens can be read from (in this order):
145
150
 
@@ -162,13 +167,12 @@ variable:
162
167
  env:
163
168
  SPHINX_GITHUB_CHANGELOG_TOKEN: ${{ github.token }}
164
169
 
165
- If you're not in one of the cases above (e.g. for ReadTheDocs, at least for the `time
166
- being`__), you'll need a personal access token. If the repository is public, the token
167
- doesn't need any special access (you can uncheck everything). For private and internal
168
- repositories, the token must have ``repo`` scope (classic tokens) or ``contents: read``
169
- access (fine-grained tokens).
170
-
171
- .. __: https://github.com/readthedocs/readthedocs.org/issues/13053
170
+ If you're not in one of the cases above and your build environment cannot use
171
+ anonymous API access reliably (e.g. rate limits), you'll need a personal access
172
+ token. If the repository is public, the token doesn't need any special access
173
+ (you can uncheck everything). For private and internal repositories, the token
174
+ must have ``repo`` scope (classic tokens) or ``contents: read`` access
175
+ (fine-grained tokens).
172
176
 
173
177
  Pass the token as the ``SPHINX_GITHUB_CHANGELOG_TOKEN`` (or ``GITHUB_TOKEN``)
174
178
  environment variable. You can also set the token as ``sphinx_github_changelog_token`` in
@@ -178,15 +182,29 @@ environment variable. You can also set the token as ``sphinx_github_changelog_to
178
182
  Extension options (``conf.py``)
179
183
  -------------------------------
180
184
 
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.
185
+ All options can also be set via environment variables of the same name in uppercase
186
+ (e.g. ``SPHINX_GITHUB_CHANGELOG_TOKEN``).
187
+
188
+ .. list-table::
189
+ :header-rows: 1
190
+ :widths: 30 10 60
191
+
192
+ * - Option
193
+ - Default
194
+ - Description
195
+ * - ``sphinx_github_changelog_token``
196
+ - ``None``
197
+ - GitHub API token. See above (please do **NOT** commit your secrets).
198
+ * - ``sphinx_github_changelog_root_repo``
199
+ - ``None``
200
+ - Root URL to the repository. Usually detected automatically.
201
+ * - ``sphinx_github_changelog_include_prereleases``
202
+ - ``True``
203
+ - Whether to include pre-releases in the changelog. Set to ``False``
204
+ to exclude them (env var accepts ``0``, ``false``, ``no``).
205
+ * - ``sphinx_github_changelog_retries``
206
+ - ``3``
207
+ - Number of retries after HTTP 429 responses from GitHub API. Will wait exponentially longer between each retry, starting at 5 second.
190
208
 
191
209
  .. _ReadTheDocs: https://readthedocs.org/
192
210
 
@@ -29,7 +29,7 @@ classifiers = [
29
29
  "Programming Language :: Python :: 3.13",
30
30
  "Programming Language :: Python :: 3.14",
31
31
  ]
32
- dependencies = ["docutils", "myst-parser>=5.1.0", "httpx", "Sphinx"]
32
+ dependencies = ["docutils", "myst-parser>=5.1.0", "httpx", "Sphinx", "tenacity"]
33
33
 
34
34
  [project.urls]
35
35
  Homepage = "https://sphinx-github-changelog.readthedocs.io/en/latest/"
@@ -44,8 +44,11 @@ dev = [
44
44
  "pytest-cov",
45
45
  "pytest-mock",
46
46
  "pytest-httpx",
47
+ "pytest-recording",
47
48
  "basedpyright",
48
49
  "pytest-subprocess>=1.6.0",
50
+ "beautifulsoup4>=4.14.3",
51
+ "html5lib>=1.1",
49
52
  ]
50
53
  docs = ["sphinx-rtd-theme"]
51
54
  types = ["types-requests", "types-docutils"]
@@ -48,22 +48,32 @@ def compute_changelog(
48
48
  "(https://github.com/:owner/:repo/releases)"
49
49
  ) from exc
50
50
 
51
- # If token is not provided, try to get it from helpers
51
+ # If token is not provided, try to get it from helpers.
52
+ # Missing credentials are tolerated: public repositories can still be
53
+ # queried anonymously via the GitHub REST API.
52
54
  token = config.token
53
55
  if not token:
54
56
  try:
55
57
  token = credentials.get_github_token(host=github_params.hostname)
56
58
  except exceptions.CouldNotExtract:
57
- return no_token(changelog_url=options.changelog_url)
59
+ token = None
58
60
 
59
- releases = github_releases.extract_releases(
60
- github_params=github_params,
61
- token=token,
62
- graphql_url=config.graphql_url,
63
- )
61
+ try:
62
+ releases = github_releases.extract_releases(
63
+ github_params=github_params,
64
+ token=token,
65
+ retries=config.retries,
66
+ )
67
+ except exceptions.GitHubAPIError:
68
+ if token is None:
69
+ return no_token(changelog_url=options.changelog_url)
70
+ raise
64
71
 
65
72
  pypi_name = extract_pypi_package_name(url=options.pypi)
66
73
 
74
+ if not config.include_prereleases:
75
+ releases = [r for r in releases if not r.is_prerelease]
76
+
67
77
  result_nodes = (
68
78
  node_for_release(release=release, pypi_name=pypi_name) for release in releases
69
79
  )
@@ -74,8 +84,9 @@ def compute_changelog(
74
84
  def no_token(changelog_url: str | None) -> list[nodes.Node]:
75
85
  par = nodes.paragraph()
76
86
  par += nodes.Text(
77
- "Changelog was not built because no GitHub authentication token was found. "
78
- "An access token can be provided using the "
87
+ "Changelog was not built because unauthenticated GitHub API access failed and "
88
+ "no GitHub authentication token was found. An access token can be provided "
89
+ "using the "
79
90
  )
80
91
  par += nodes.literal("", "SPHINX_GITHUB_CHANGELOG_TOKEN")
81
92
  par += nodes.Text(" environment variable or the ")
@@ -113,9 +124,10 @@ def extract_pypi_package_name(url: str | None) -> str | None:
113
124
 
114
125
 
115
126
  def get_release_title(title: str | None, tag: str):
127
+ version = tag.removeprefix("v")
116
128
  if not title:
117
- return tag
118
- return title if tag in title else f"{tag}: {title}"
129
+ return version
130
+ return title if version in title else f"{version}: {title}"
119
131
 
120
132
 
121
133
  def node_for_release(
@@ -126,12 +138,13 @@ def node_for_release(
126
138
  return None # For now, draft releases are excluded
127
139
 
128
140
  tag = release.tag_name
141
+ version = tag.removeprefix("v")
129
142
  title = release.name
130
143
  date = release.published_at.isoformat()
131
144
  title = get_release_title(title=title, tag=tag)
132
145
 
133
146
  # Section
134
- id_section = nodes.make_id("release-" + tag)
147
+ id_section = nodes.make_id("release-" + version)
135
148
  section = nodes.section(ids=[id_section])
136
149
 
137
150
  section += nodes.title(text=title)
@@ -143,7 +156,7 @@ def node_for_release(
143
156
  subtitle += nodes.reference("", "GitHub", refuri=release.url)
144
157
  if pypi_name:
145
158
  subtitle += nodes.Text(" - ")
146
- url = f"https://pypi.org/project/{pypi_name}/{tag}/"
159
+ url = f"https://pypi.org/project/{pypi_name}/{version}/"
147
160
  subtitle += nodes.reference("", "PyPI", refuri=url)
148
161
 
149
162
  subtitle_paragraph = nodes.paragraph()
@@ -0,0 +1,64 @@
1
+ from __future__ import annotations
2
+
3
+ import dataclasses
4
+ import os
5
+ from collections.abc import Iterator
6
+ from typing import Any, ClassVar
7
+
8
+
9
+ @dataclasses.dataclass
10
+ class ChangelogDirectiveOptions:
11
+ changelog_url: str | None = None
12
+ github: str | None = None
13
+ pypi: str | None = None
14
+
15
+ @classmethod
16
+ def from_options(cls, options: dict[str, str]):
17
+ return cls(
18
+ changelog_url=options.get("changelog-url"),
19
+ github=options.get("github"),
20
+ pypi=options.get("pypi"),
21
+ )
22
+
23
+
24
+ @dataclasses.dataclass
25
+ class ChangelogConfig:
26
+ token: str | None = None
27
+ root_repo: str | None = None
28
+ include_prereleases: bool = True
29
+ retries: int = 3
30
+
31
+ prefix: ClassVar[str] = "sphinx_github_changelog"
32
+
33
+ @classmethod
34
+ def get_config_defaults(cls) -> Iterator[tuple[str, str | bool | int | 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 | int | None = (
40
+ env_value.lower() not in ("0", "false", "no")
41
+ if env_value
42
+ else bool(field.default)
43
+ )
44
+ elif field.type == "int":
45
+ if env_value is not None:
46
+ default = int(env_value)
47
+ elif isinstance(field.default, int):
48
+ default = field.default
49
+ else:
50
+ raise TypeError(
51
+ f"Unexpected default type for {field.name}: {field.default!r}"
52
+ )
53
+ else:
54
+ default = env_value
55
+ yield option_name, default
56
+
57
+ @classmethod
58
+ def from_sphinx_env_config(cls, sphinx_config: Any):
59
+ return cls(
60
+ token=sphinx_config.sphinx_github_changelog_token,
61
+ root_repo=sphinx_config.sphinx_github_changelog_root_repo,
62
+ include_prereleases=sphinx_config.sphinx_github_changelog_include_prereleases,
63
+ retries=sphinx_config.sphinx_github_changelog_retries,
64
+ )
@@ -0,0 +1,144 @@
1
+ from __future__ import annotations
2
+
3
+ import dataclasses
4
+ import datetime
5
+ from collections.abc import Callable, Sequence
6
+
7
+ import httpx
8
+ from tenacity import (
9
+ Retrying,
10
+ nap,
11
+ retry_if_exception_type,
12
+ stop_after_attempt,
13
+ wait_exponential,
14
+ )
15
+
16
+ from . import exceptions, urls
17
+
18
+
19
+ class GitHubRateLimitError(Exception):
20
+ """Raised internally to trigger retry logic on HTTP 429."""
21
+
22
+
23
+ @dataclasses.dataclass
24
+ class Release:
25
+ name: str | None
26
+ description: str | None
27
+ url: str
28
+ tag_name: str
29
+ published_at: datetime.date
30
+ is_draft: bool
31
+ is_prerelease: bool
32
+
33
+ @classmethod
34
+ def from_rest(cls, data: dict) -> Release:
35
+ published_or_created = data.get("published_at") or data.get("created_at")
36
+ if not published_or_created:
37
+ raise exceptions.GitHubAPIError(
38
+ f"GitHub API error release has no publication date:\n{data!r}"
39
+ )
40
+ return cls(
41
+ name=data["name"],
42
+ description=data["body"],
43
+ url=data["html_url"],
44
+ tag_name=data["tag_name"],
45
+ published_at=datetime.date.fromisoformat(published_or_created[:10]),
46
+ is_draft=data["draft"],
47
+ is_prerelease=data["prerelease"],
48
+ )
49
+
50
+
51
+ def extract_releases(
52
+ github_params: urls.GitHubParams,
53
+ token: str | None,
54
+ retries: int,
55
+ ) -> Sequence[Release]:
56
+ page = 1
57
+ releases: list[Release] = []
58
+ while True:
59
+ result = github_call(
60
+ url=github_params.releases_api_url,
61
+ token=token,
62
+ params={"per_page": 100, "page": page},
63
+ retries=retries,
64
+ )
65
+ if not result:
66
+ break
67
+ try:
68
+ releases.extend(Release.from_rest(r) for r in result)
69
+ except (KeyError, TypeError) as exc:
70
+ raise exceptions.GitHubAPIError(
71
+ f"GitHub API error unexpected format:\n{result!r}"
72
+ ) from exc
73
+ page += 1
74
+
75
+ # Sort by publication date descending
76
+ return sorted(
77
+ releases,
78
+ key=lambda r: r.published_at,
79
+ reverse=True,
80
+ )
81
+
82
+
83
+ def github_call(
84
+ url: str,
85
+ token: str | None,
86
+ params: dict[str, int],
87
+ retries: int,
88
+ sleep: Callable[[float], None] = nap.sleep,
89
+ ) -> list[dict]:
90
+ headers = {
91
+ "Accept": "application/vnd.github+json",
92
+ }
93
+ if token:
94
+ headers["Authorization"] = f"token {token}"
95
+
96
+ response: httpx.Response | None = None
97
+ total_attempts = max(1, retries + 1)
98
+ try:
99
+ for attempt in Retrying(
100
+ stop=stop_after_attempt(total_attempts),
101
+ retry=retry_if_exception_type(GitHubRateLimitError),
102
+ wait=wait_exponential(multiplier=5, min=5),
103
+ sleep=sleep,
104
+ reraise=True,
105
+ ):
106
+ with attempt:
107
+ try:
108
+ response = httpx.get(
109
+ url,
110
+ params=params,
111
+ headers=headers,
112
+ ).raise_for_status()
113
+ except httpx.HTTPStatusError as exc:
114
+ if exc.response.status_code == 429:
115
+ raise GitHubRateLimitError(exc.response.text) from exc
116
+ raise
117
+
118
+ except httpx.HTTPStatusError as exc:
119
+ if exc.response.status_code == 401:
120
+ raise exceptions.GitHubAPIError(
121
+ "GitHub API authentication failed (401 Unauthorized)."
122
+ ) from exc
123
+ raise exceptions.GitHubAPIError(
124
+ f"Unexpected GitHub API error status code: {exc.response.status_code}\n"
125
+ f"{exc.response.text}"
126
+ ) from exc
127
+ except GitHubRateLimitError as exc:
128
+ raise exceptions.GitHubAPIError(
129
+ f"GitHub API rate limited (429) after {retries} retries."
130
+ ) from exc
131
+ except httpx.HTTPError as exc:
132
+ raise exceptions.GitHubAPIError(
133
+ "Could not retrieve changelog from github: " + str(exc)
134
+ ) from exc
135
+
136
+ if response is None:
137
+ raise NotImplementedError("Unreachable: retry loop completed without response")
138
+
139
+ response_payload = response.json()
140
+ if not isinstance(response_payload, list):
141
+ raise exceptions.GitHubAPIError(
142
+ f"GitHub API error unexpected format:\n{response_payload!r}"
143
+ )
144
+ return response_payload
@@ -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
 
@@ -1,7 +1,7 @@
1
1
  """
2
2
  Utilities for working with git remotes and GitHub URLs.
3
3
 
4
- Includes functions to parse remote URLs and derive GraphQL endpoints.
4
+ Includes functions to parse remote URLs and derive API endpoints.
5
5
  """
6
6
 
7
7
  from __future__ import annotations
@@ -78,10 +78,14 @@ class GitHubParams:
78
78
  return f"https://{self.hostname}/{self.owner}/{self.repo}"
79
79
 
80
80
  @property
81
- def graphql_url(self) -> str:
81
+ def rest_api_url(self) -> str:
82
82
  if self.is_github_com:
83
- return "https://api.github.com/graphql"
84
- return f"https://{self.hostname}/api/graphql"
83
+ return "https://api.github.com"
84
+ return f"https://{self.hostname}/api/v3"
85
+
86
+ @property
87
+ def releases_api_url(self) -> str:
88
+ return f"{self.rest_api_url}/repos/{self.owner}/{self.repo}/releases"
85
89
 
86
90
 
87
91
  def extract_github_params(