sphinx-github-changelog 2.2.0__tar.gz → 2.3.1__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 (62) hide show
  1. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/.github/renovate.json5 +2 -1
  2. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/.github/workflows/autofix.yml +6 -3
  3. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/.github/workflows/ci.yml +25 -14
  4. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/.github/workflows/coverage-comment.yml +1 -1
  5. sphinx_github_changelog-2.3.1/.pre-commit-config.yaml +59 -0
  6. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/CONTRIBUTING.rst +29 -2
  7. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/PKG-INFO +21 -15
  8. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/README.rst +17 -13
  9. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/pyproject.toml +7 -2
  10. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/sphinx_github_changelog/changelog.py +17 -9
  11. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/sphinx_github_changelog/config.py +13 -4
  12. sphinx_github_changelog-2.3.1/sphinx_github_changelog/github_releases.py +144 -0
  13. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/sphinx_github_changelog/urls.py +8 -4
  14. sphinx_github_changelog-2.3.1/tests/acceptance/cassettes/test_all/test_build.yaml +176 -0
  15. sphinx_github_changelog-2.3.1/tests/acceptance/cassettes/test_all/test_build_404.yaml +69 -0
  16. sphinx_github_changelog-2.3.1/tests/acceptance/changelog.html +272 -0
  17. sphinx_github_changelog-2.3.1/tests/acceptance/test_all.py +61 -0
  18. sphinx_github_changelog-2.3.1/tests/conftest.py +103 -0
  19. {sphinx_github_changelog-2.2.0/tests/roots/test-error → sphinx_github_changelog-2.3.1/tests/roots/test-404}/conf.py +0 -2
  20. sphinx_github_changelog-2.3.1/tests/roots/test-404/index.rst +4 -0
  21. sphinx_github_changelog-2.3.1/tests/roots/test-all/conf.py +5 -0
  22. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/tests/roots/test-all/index.rst +1 -1
  23. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/tests/unit/test_changelog.py +21 -4
  24. sphinx_github_changelog-2.3.1/tests/unit/test_config.py +40 -0
  25. sphinx_github_changelog-2.3.1/tests/unit/test_github_releases.py +236 -0
  26. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/tests/unit/test_urls.py +9 -4
  27. sphinx_github_changelog-2.3.1/uv.lock +1399 -0
  28. sphinx_github_changelog-2.2.0/.pre-commit-config.yaml +0 -58
  29. sphinx_github_changelog-2.2.0/sphinx_github_changelog/github_releases.py +0 -95
  30. sphinx_github_changelog-2.2.0/tests/acceptance/changelog.html +0 -71
  31. sphinx_github_changelog-2.2.0/tests/acceptance/test_all.py +0 -109
  32. sphinx_github_changelog-2.2.0/tests/conftest.py +0 -54
  33. sphinx_github_changelog-2.2.0/tests/unit/test_github_releases.py +0 -115
  34. sphinx_github_changelog-2.2.0/uv.lock +0 -961
  35. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/.editorconfig +0 -0
  36. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/.github/CODEOWNERS +0 -0
  37. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/.github/PULL_REQUEST_TEMPLATE.md +0 -0
  38. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/.github/release.yml +0 -0
  39. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/.gitignore +0 -0
  40. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/.readthedocs.yml +0 -0
  41. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/CHANGELOG.rst +0 -0
  42. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/CODE_OF_CONDUCT.rst +0 -0
  43. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/LICENSE +0 -0
  44. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/docs/Makefile +0 -0
  45. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/docs/conduct.rst +0 -0
  46. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/docs/conf.py +0 -0
  47. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/docs/contributing.rst +0 -0
  48. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/docs/index.rst +0 -0
  49. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/scripts/README.md +0 -0
  50. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/scripts/docs +0 -0
  51. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/scripts/lint +0 -0
  52. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/scripts/tests +0 -0
  53. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/sphinx_github_changelog/__init__.py +0 -0
  54. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/sphinx_github_changelog/credentials.py +0 -0
  55. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/sphinx_github_changelog/exceptions.py +0 -0
  56. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/sphinx_github_changelog/setup.py +0 -0
  57. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/tests/__init__.py +0 -0
  58. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/tests/acceptance/__init__.py +0 -0
  59. {sphinx_github_changelog-2.2.0/tests/roots/test-all → sphinx_github_changelog-2.3.1/tests/roots/test-error}/conf.py +0 -0
  60. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/tests/roots/test-error/index.rst +0 -0
  61. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/tests/unit/__init__.py +0 -0
  62. {sphinx_github_changelog-2.2.0 → sphinx_github_changelog-2.3.1}/tests/unit/test_git.py +0 -0
@@ -1,7 +1,8 @@
1
1
  {
2
- extends: ["config:recommended", ":enablePreCommit"],
2
+ extends: ["config:recommended", ":enablePreCommit", "helpers:pinGitHubActionDigests"],
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,
@@ -1,6 +1,9 @@
1
1
  name: autofix.ci
2
2
  on: [pull_request]
3
3
 
4
+ env:
5
+ UV_FROZEN: "true"
6
+
4
7
  permissions:
5
8
  contents: read
6
9
 
@@ -9,13 +12,13 @@ jobs:
9
12
  name: Autofix
10
13
  runs-on: ubuntu-latest
11
14
  steps:
12
- - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
15
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
13
16
  with:
14
17
  persist-credentials: false
15
18
 
16
19
  - name: Set up UV
17
20
  id: setup-uv
18
- uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
21
+ uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
19
22
  with:
20
23
  enable-cache: false
21
24
 
@@ -23,7 +26,7 @@ jobs:
23
26
  run: uv sync --all-groups
24
27
 
25
28
  - name: Run prek
26
- uses: j178/prek-action@bdca6f102f98e2b4c7029491a53dfd366469e33d # v2.0.4
29
+ uses: j178/prek-action@44924fe9ef4a6f88253c4b6b1bf11c689d3ce53d # v3.1.0
27
30
 
28
31
  - name: Commits back to branch if necessary
29
32
  uses: autofix-ci/action@c5b2d67aa2274e7b5a18224e8171550871fc7e4a # v1.3.4
@@ -8,6 +8,9 @@ on:
8
8
  tags:
9
9
  - "*"
10
10
 
11
+ env:
12
+ UV_FROZEN: "true"
13
+
11
14
  permissions:
12
15
  contents: read
13
16
 
@@ -16,13 +19,13 @@ jobs:
16
19
  name: linting
17
20
  runs-on: ubuntu-latest
18
21
  steps:
19
- - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
22
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
20
23
  with:
21
24
  persist-credentials: false
22
25
 
23
26
  - name: Set up UV
24
27
  id: setup-uv
25
- uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
28
+ uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
26
29
  with:
27
30
  enable-cache: false
28
31
 
@@ -30,24 +33,26 @@ jobs:
30
33
  run: uv sync --all-groups
31
34
 
32
35
  - name: Run prek
33
- uses: j178/prek-action@bdca6f102f98e2b4c7029491a53dfd366469e33d # v2.0.4
36
+ uses: j178/prek-action@44924fe9ef4a6f88253c4b6b1bf11c689d3ce53d # v3.1.0
37
+ env:
38
+ PREK_SKIP: no-commit-to-branch
34
39
 
35
40
  tests:
36
41
  strategy:
37
42
  matrix:
38
- python_version: ["3.11", "3.12", "3.13", "3.14"]
43
+ python_version: ["3.11", "3.12", "3.13", "3.14", "3.15"]
39
44
 
40
45
  name: "py${{ matrix.python_version }}"
41
46
  runs-on: ubuntu-latest
42
47
 
43
48
  steps:
44
- - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
49
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
45
50
  with:
46
51
  persist-credentials: false
47
52
 
48
53
  - name: Set up UV
49
54
  id: setup-uv
50
- uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
55
+ uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
51
56
  with:
52
57
  python-version: ${{ matrix.python_version }}
53
58
  enable-cache: false
@@ -58,7 +63,7 @@ jobs:
58
63
  COVERAGE_FILE: ".coverage.${{ matrix.python_version }}"
59
64
 
60
65
  - name: Store coverage file
61
- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
66
+ uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
62
67
  with:
63
68
  name: coverage-${{ matrix.python_version }}
64
69
  path: .coverage.${{ matrix.python_version }}
@@ -72,27 +77,33 @@ jobs:
72
77
  contents: write
73
78
  pull-requests: write
74
79
  steps:
75
- - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
80
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
76
81
  with:
77
82
  persist-credentials: true
78
83
 
79
- - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
84
+ - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
80
85
  with:
81
86
  pattern: coverage-*
82
87
  merge-multiple: true
83
88
 
89
+ - name: Prepare merged coverage data
90
+ run: |
91
+ pipx run coverage combine
92
+
84
93
  - name: Display coverage
85
- uses: ewjoachim/python-coverage-comment-action@63f52f4fbbffada6e8dee8ec432de7e01df9ba79 # v3.41
94
+ uses: ewjoachim/python-coverage-comment-action@e5fb2218463c3377f3504b0c5b5646ed53da7a2f # v4.5
86
95
  with:
87
- MERGE_COVERAGE_FILES: true
88
96
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
89
97
 
90
98
  - name: Store Pull Request comment to be posted
91
- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
99
+ uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
92
100
  with:
93
101
  name: python-coverage-comment-action
94
102
  path: python-coverage-comment-action.txt
95
103
 
104
+ - name: Enforce coverage >= 100%
105
+ run: pipx run coverage report --fail-under=100
106
+
96
107
  publish:
97
108
  name: Publish package to PyPI
98
109
  if: github.event_name == 'push' && github.ref_type == 'tag'
@@ -104,7 +115,7 @@ jobs:
104
115
  - tests
105
116
  - lint
106
117
  steps:
107
- - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
118
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
108
119
  with:
109
120
  persist-credentials: false
110
121
 
@@ -112,4 +123,4 @@ jobs:
112
123
  run: pipx run uv build
113
124
 
114
125
  - name: Publish package distributions to PyPI
115
- uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
126
+ uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
@@ -20,7 +20,7 @@ jobs:
20
20
  # DO NOT run actions/checkout here, for securitity reasons
21
21
  # For details, refer to https://securitylab.github.com/research/github-actions-preventing-pwn-requests/
22
22
  - name: Post comment
23
- uses: ewjoachim/python-coverage-comment-action@63f52f4fbbffada6e8dee8ec432de7e01df9ba79 # v3.41
23
+ uses: ewjoachim/python-coverage-comment-action@e5fb2218463c3377f3504b0c5b5646ed53da7a2f # v4.5
24
24
  with:
25
25
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
26
26
  GITHUB_PR_RUN_ID: ${{ github.event.workflow_run.id }}
@@ -0,0 +1,59 @@
1
+ repos:
2
+ - repo: builtin
3
+ hooks:
4
+ # File names
5
+ - id: check-case-conflict
6
+ # File formats
7
+ - id: pretty-format-json
8
+ - id: check-json
9
+ - id: check-toml
10
+ - id: check-yaml
11
+ # Executables
12
+ - id: check-executables-have-shebangs
13
+ - id: check-shebang-scripts-are-executable
14
+ # Git shenanigans
15
+ - id: check-merge-conflict
16
+ - id: check-added-large-files
17
+ # Whitespace
18
+ - id: end-of-file-fixer
19
+ - id: trailing-whitespace
20
+ - id: mixed-line-ending
21
+ - id: no-commit-to-branch
22
+
23
+ - repo: local
24
+ hooks:
25
+ - id: ruff-check
26
+ name: ruff check
27
+ entry: uv run --group lint ruff check --force-exclude --fix --unsafe-fixes --show-fixes
28
+ language: system
29
+ types_or: [python, pyi]
30
+ require_serial: true
31
+
32
+ - id: ruff-format
33
+ name: ruff format
34
+ entry: uv run --group lint ruff format --force-exclude
35
+ language: system
36
+ types_or: [python, pyi]
37
+ require_serial: true
38
+
39
+ - id: uv-lock
40
+ name: uv-lock
41
+ entry: env UV_FROZEN=false uv lock
42
+ language: system
43
+ files: ^(uv\.lock|pyproject\.toml|uv\.toml)$
44
+ pass_filenames: false
45
+
46
+ - id: basedpyright
47
+ name: basedpyright
48
+ entry: uv run --group lint basedpyright
49
+ language: system
50
+ types_or: [python, pyi]
51
+ require_serial: true
52
+
53
+ - id: zizmor
54
+ name: zizmor
55
+ entry: uv run --group lint zizmor --no-progress --fix=all
56
+ language: system
57
+ types: [yaml]
58
+ files: (\.github/(workflows/.*|dependabot\.ya?ml))|(action\.ya?ml)$
59
+ require_serial: true
@@ -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
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: sphinx-github-changelog
3
- Version: 2.2.0
3
+ Version: 2.3.1
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
@@ -15,6 +15,7 @@ Classifier: Programming Language :: Python :: 3.11
15
15
  Classifier: Programming Language :: Python :: 3.12
16
16
  Classifier: Programming Language :: Python :: 3.13
17
17
  Classifier: Programming Language :: Python :: 3.14
18
+ Classifier: Programming Language :: Python :: 3.15
18
19
  Classifier: Topic :: Documentation
19
20
  Classifier: Topic :: Documentation :: Sphinx
20
21
  Classifier: Typing :: Typed
@@ -23,6 +24,7 @@ Requires-Dist: docutils
23
24
  Requires-Dist: httpx
24
25
  Requires-Dist: myst-parser>=5.1.0
25
26
  Requires-Dist: sphinx
27
+ Requires-Dist: tenacity
26
28
  Description-Content-Type: text/x-rst
27
29
 
28
30
  Sphinx Github Changelog: Build a sphinx changelog from GitHub Releases
@@ -154,7 +156,7 @@ git remotes in this order:
154
156
  1. ``upstream`` remote
155
157
  2. ``origin`` remote
156
158
 
157
- The GraphQL API and GitHub root URL are derived from this URL.
159
+ The GitHub API base URL and GitHub root URL are derived from this URL.
158
160
 
159
161
  If for any reason, you'd rather provide the repository explicitly (e.g. the doc
160
162
  repo doesn't match the repo you're releasing from, or anything else), you can
@@ -165,8 +167,13 @@ details.
165
167
  Authentication
166
168
  --------------
167
169
 
168
- The extension uses the GitHub GraphQL API to retrieve the changelog. This
169
- requires authentication using a GitHub API token.
170
+ The extension uses the GitHub Releases REST API to retrieve the changelog.
171
+
172
+ For public repositories, this can usually work without authentication, though it's not
173
+ recommended as GitHub applies IP-based rate limits, so this may make your builds flaky.
174
+ Note that there will be automatic retries after HTTP 429 responses, controlled by the
175
+ ``sphinx_github_changelog_retries`` option (see below). For private repositories (or
176
+ when unauthenticated requests are rate limited), you need a GitHub API token.
170
177
 
171
178
  Tokens can be read from (in this order):
172
179
 
@@ -189,13 +196,12 @@ variable:
189
196
  env:
190
197
  SPHINX_GITHUB_CHANGELOG_TOKEN: ${{ github.token }}
191
198
 
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
199
+ If you're not in one of the cases above and your build environment cannot use
200
+ anonymous API access reliably (e.g. rate limits), you'll need a personal access
201
+ token. If the repository is public, the token doesn't need any special access
202
+ (you can uncheck everything). For private and internal repositories, the token
203
+ must have ``repo`` scope (classic tokens) or ``contents: read`` access
204
+ (fine-grained tokens).
199
205
 
200
206
  Pass the token as the ``SPHINX_GITHUB_CHANGELOG_TOKEN`` (or ``GITHUB_TOKEN``)
201
207
  environment variable. You can also set the token as ``sphinx_github_changelog_token`` in
@@ -221,13 +227,13 @@ All options can also be set via environment variables of the same name in upperc
221
227
  * - ``sphinx_github_changelog_root_repo``
222
228
  - ``None``
223
229
  - 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
230
  * - ``sphinx_github_changelog_include_prereleases``
228
231
  - ``True``
229
232
  - Whether to include pre-releases in the changelog. Set to ``False``
230
233
  to exclude them (env var accepts ``0``, ``false``, ``no``).
234
+ * - ``sphinx_github_changelog_retries``
235
+ - ``3``
236
+ - Number of retries after HTTP 429 responses from GitHub API. Will wait exponentially longer between each retry, starting at 5 second.
231
237
 
232
238
  .. _ReadTheDocs: https://readthedocs.org/
233
239
 
@@ -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
@@ -194,13 +198,13 @@ All options can also be set via environment variables of the same name in upperc
194
198
  * - ``sphinx_github_changelog_root_repo``
195
199
  - ``None``
196
200
  - 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
201
  * - ``sphinx_github_changelog_include_prereleases``
201
202
  - ``True``
202
203
  - Whether to include pre-releases in the changelog. Set to ``False``
203
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.
204
208
 
205
209
  .. _ReadTheDocs: https://readthedocs.org/
206
210
 
@@ -28,8 +28,9 @@ classifiers = [
28
28
  "Programming Language :: Python :: 3.12",
29
29
  "Programming Language :: Python :: 3.13",
30
30
  "Programming Language :: Python :: 3.14",
31
+ "Programming Language :: Python :: 3.15",
31
32
  ]
32
- dependencies = ["docutils", "myst-parser>=5.1.0", "httpx", "Sphinx"]
33
+ dependencies = ["docutils", "myst-parser>=5.1.0", "httpx", "Sphinx", "tenacity"]
33
34
 
34
35
  [project.urls]
35
36
  Homepage = "https://sphinx-github-changelog.readthedocs.io/en/latest/"
@@ -44,15 +45,19 @@ dev = [
44
45
  "pytest-cov",
45
46
  "pytest-mock",
46
47
  "pytest-httpx",
47
- "basedpyright",
48
+ "pytest-recording",
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"]
55
+ lint = ["basedpyright", "ruff", "zizmor"]
52
56
 
53
57
  [tool.uv]
54
58
  default-groups = ["dev", "docs"]
55
59
  exclude-newer = "5 days"
60
+ exclude-newer-package = { certifi = false }
56
61
 
57
62
  [tool.basedpyright]
58
63
  exclude = ["tests", ".venv", "scripts", ".github"]
@@ -48,19 +48,26 @@ 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
 
@@ -77,8 +84,9 @@ def compute_changelog(
77
84
  def no_token(changelog_url: str | None) -> list[nodes.Node]:
78
85
  par = nodes.paragraph()
79
86
  par += nodes.Text(
80
- "Changelog was not built because no GitHub authentication token was found. "
81
- "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 "
82
90
  )
83
91
  par += nodes.literal("", "SPHINX_GITHUB_CHANGELOG_TOKEN")
84
92
  par += nodes.Text(" environment variable or the ")
@@ -25,22 +25,31 @@ class ChangelogDirectiveOptions:
25
25
  class ChangelogConfig:
26
26
  token: str | None = None
27
27
  root_repo: str | None = None
28
- graphql_url: str | None = None
29
28
  include_prereleases: bool = True
29
+ retries: int = 3
30
30
 
31
31
  prefix: ClassVar[str] = "sphinx_github_changelog"
32
32
 
33
33
  @classmethod
34
- def get_config_defaults(cls) -> Iterator[tuple[str, str | bool | None]]:
34
+ def get_config_defaults(cls) -> Iterator[tuple[str, str | bool | int | None]]:
35
35
  for field in dataclasses.fields(cls):
36
36
  option_name = f"{cls.prefix}_{field.name}"
37
37
  env_value = os.environ.get(option_name.upper())
38
38
  if field.type == "bool":
39
- default: str | bool | None = (
39
+ default: str | bool | int | None = (
40
40
  env_value.lower() not in ("0", "false", "no")
41
41
  if env_value
42
42
  else bool(field.default)
43
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
+ )
44
53
  else:
45
54
  default = env_value
46
55
  yield option_name, default
@@ -50,6 +59,6 @@ class ChangelogConfig:
50
59
  return cls(
51
60
  token=sphinx_config.sphinx_github_changelog_token,
52
61
  root_repo=sphinx_config.sphinx_github_changelog_root_repo,
53
- graphql_url=sphinx_config.sphinx_github_changelog_graphql_url,
54
62
  include_prereleases=sphinx_config.sphinx_github_changelog_include_prereleases,
63
+ retries=sphinx_config.sphinx_github_changelog_retries,
55
64
  )