Merge pull request #147 from lordmauve/lordmauve/issue146

Author: ewjoachim

.github/workflows/ci.yml

@@ -3,41 +3,29 @@ name: CI
 on:
   pull_request:
   push:
-    branches:
-      - "main"
-    tags:
-      - "*"
 
 jobs:
   build:
     strategy:
       matrix:
-        include:
-          - python_version: "3.8"
-            script: tests
-          - python_version: "3.9"
-            script: tests
-          - python_version: "3.10"
-            script: tests
-          - python_version: "3.11"
-            script: tests
-          - python_version: "3.12"
-            script: tests
+        python_version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+        script: [tests]
+      fail-fast: false
 
     name: "py${{ matrix.python_version }} / ${{ matrix.script }}"
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
 
       - name: Set up Python
         id: setup-python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python_version }}
 
       - name: Pip, Pre-commit & Poetry caches
-        uses: actions/cache@v2
+        uses: actions/cache@v4
         with:
           path: |
             ~/.cache/
@@ -53,6 +41,7 @@ jobs:
         run: poetry run scripts/${{ matrix.script }}
         env:
           PYTEST_ADDOPTS: "--cov-report=xml"
+          GITHUB_TOKEN: ${{ github.token }}
 
   report-status:
     name: success

.github/workflows/publish.yml

@@ -10,16 +10,16 @@ jobs:
     name: Publish package to PyPI
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
 
       - name: Set up Python
         id: setup-python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python_version }}
 
       - name: Pip, Pre-commit & Poetry caches
-        uses: actions/cache@v2
+        uses: actions/cache@v4
         with:
           path: |
             ~/.cache/
@@ -32,7 +32,7 @@ jobs:
         run: poetry install
 
       - name: Wait for tests to succeed
-        uses: fountainhead/action-wait-for-check@v1.0.0
+        uses: fountainhead/action-wait-for-check@v1.2.0
         id: wait-for-ci
         with:
           token: ${{ secrets.GITHUB_TOKEN }}

.readthedocs.yml

@@ -7,6 +7,7 @@ version: 2
 
 sphinx:
   fail_on_warning: true
+  configuration: docs/conf.py
 
 build:
   os: ubuntu-lts-latest

CHANGELOG.rst

@@ -6,5 +6,4 @@ This documentation itself is "drinking its own champagne": it uses
 
 .. changelog::
     :changelog-url: https://sphinx-github-changelog.readthedocs.io/en/stable/#changelog
-    :github: https://github.com/peopledoc/sphinx-github-changelog/releases/
     :pypi: https://pypi.org/project/sphinx-github-changelog/

README.rst

@@ -51,13 +51,6 @@ In your Sphinx documentation ``conf.py``:
         "sphinx_github_changelog",
     ]
 
-    # Provide a GitHub API token:
-    # Pass the SPHINX_GITHUB_CHANGELOG_TOKEN environment variable to your build
-    # OR
-    # You can retrieve your token any other way you want, but of course, please
-    # don't commit secrets to git, especially on a public repository
-    sphinx_github_changelog_token = ...
-
 In your documentation:
 
 .. code-block:: restructuredtext
@@ -67,6 +60,12 @@ In your documentation:
         :github: https://github.com/you/your-project/releases/
         :pypi: https://pypi.org/project/your-project/
 
+or more minimally (but not necessarily recommended):
+
+.. code-block:: restructuredtext
+
+    .. changelog::
+
 
 See the end result for this project on ReadTheDocs__.
 
@@ -139,27 +138,68 @@ draft GitHub Release and press "Publish Release". That's it.
 Reference documentation
 =======================
 
+Automatic Configuration
+-----------------------
+
+The extension can automatically detect the GitHub repository URL from your
+git remotes in this order:
+
+1. ``upstream`` remote
+2. ``origin`` remote
+
+The GraphQL API and GitHub root URL are derived from this URL.
+
+If for any reason, you'd rather provide the repository explicitly (e.g. the doc
+repo doesn't match the repo you're releasing from, or anything else), you can
+define the ``:github:`` attribute to the directive. See directive_ for
+details.
+
+
+Authentication
+--------------
+
+The extension uses the GitHub GraphQL API to retrieve the changelog. This
+requires authentication using a GitHub API token.
+
+However if you use git over HTTPS, or the ``gh`` CLI, you probably already have a
+suitable token, which ``sphinx-github-changelog`` will automatically use.
+
+In CI like GitHub Actions you can pass a token explicitly as an environment
+variable:
+
+.. code-block:: yaml
+
+    - name: Build documentation
+      run: make html
+      env:
+        SPHINX_GITHUB_CHANGELOG_TOKEN: ${{ github.token }}
+
+In remaining cases you may need to create a personal access token. If the
+repository is public, the token doesn't need any special access (you can
+uncheck eveything). For private and internal repositories, the token must
+have ``repo`` scope (classic tokens) or ``contents: read`` access (fine-grained
+tokens).
+
+Pass the token as the ``SPHINX_GITHUB_CHANGELOG_TOKEN`` environment variable.
+You can also set the token as ``sphinx_github_changelog_token`` in ``conf.py``
+but you should never commit secrets such as this.
+
+
 Extension options (``conf.py``)
 -------------------------------
 
-- ``sphinx_github_changelog_token``: GitHub API token.
-  If the repository is public, the token doesn't need any special access (you
-  can uncheck eveything). If the repository is private, you'll need to give
-  your token enough access to read the releases. Defaults to the value of the
-  environment variable ``SPHINX_GITHUB_CHANGELOG_TOKEN``. If no value is
-  provided, the build will still pass but the changelog will not be built, and
-  a link to the ``changelog-url`` will be displayed (if provided).
+- ``sphinx_github_changelog_token``: GitHub API token, if needed.
 
-- ``sphinx_github_changelog_root_repo`` (optional): Root url to the repository,
-  defaults to "https://github.com/". Useful if you're using a self-hosted GitHub
-  instance.
+Two options are accepted for backwards compatibility, but are likely detected
+automatically from the ``:github:`` parameter to the directive:
 
-- ``sphinx_github_changelog_graphql_url`` (optional): Url to graphql api, defaults
-  to "https://api.github.com/graphql". Useful if you're using a self-hosted GitHub
-  instance.
+- ``sphinx_github_changelog_root_repo`` (optional): Root URL to the repository.
+- ``sphinx_github_changelog_graphql_url`` (optional): URL to GraphQL API.
 
 .. _ReadTheDocs: https://readthedocs.org/
 
+.. _directive:
+
 Directive
 ---------
 
@@ -173,7 +213,8 @@ Directive
 Attributes
 ~~~~~~~~~~
 
-- ``github`` (**required**): URL to the releases page of the repository.
+- ``github`` (optional): URL to the releases page of the repository.
+  If not provided, auto‑detected from your git remote, as described above.
 - ``changelog-url`` (optional): URL to the built version of your changelog.
   ``sphinx-github-changelog`` will display a link to your built changelog if the GitHub
   token is not provided (hopefully, this does not happen in your built documentation)

sphinx_github_changelog/changelog.py

@@ -8,6 +8,8 @@
 # https://github.com/tk0miya/docutils-stubs/issues/33
 from docutils.parsers.rst import Directive, directives  # type: ignore
 
+from . import credentials, urls
+
 
 class ChangelogError(Exception):
     pass
@@ -46,10 +48,39 @@ def compute_changelog(
     root_url: Optional[str] = None,
     graphql_url: Optional[str] = None,
 ) -> List[nodes.Node]:
+
+    if options.get("github"):
+        # If a github URL is explicitly provided, validate that it is in
+        # the correct format i.e. refers to the /releases page.
+        github_url = options["github"]
+        root_url = root_url or urls.get_root_url(github_url)
+        owner_repo = extract_github_repo_name(github_url, root_url)
+    else:
+        # If no github URL is provided, try to get it from the git remote
+        # and validate that it is in the correct format.
+        remote_url = urls.get_default_github_url()
+        parsed_repo = remote_url and urls.parse_github_repo_from_url(remote_url)
+        if not parsed_repo:
+            raise ChangelogError(
+                "No :github: release URL provided and unable to determine it from "
+                "git remotes. Please provide a GitHub release URL in the format "
+                "(https://github.com/:owner/:repo/releases)"
+            )
+        owner_repo = parsed_repo
+        github_url = f"{remote_url}/releases"
+
+    # If graphql_url is not provided, derive from github_url
+    if not graphql_url:
+        graphql_url = urls.get_github_graphql_url(github_url)
+
+    # If token is not provided, try to get it from helpers
+    if not token:
+        host = urls.get_github_host_from_url(github_url)
+        token = credentials.get_github_token(host)
+
     if not token:
         return no_token(changelog_url=options.get("changelog-url"))
 
-    owner_repo = extract_github_repo_name(url=options["github"], root_url=root_url)
     releases = extract_releases(
         owner_repo=owner_repo, token=token, graphql_url=graphql_url
     )
@@ -65,9 +96,18 @@ def compute_changelog(
 
 def no_token(changelog_url: Optional[str]) -> List[nodes.Node]:
     par = nodes.paragraph()
-    par += nodes.Text("Changelog was not built because ")
+    par += nodes.Text(
+        "Changelog was not built because no GitHub authentication token was found. "
+        "An access token can be provided using the "
+    )
+    par += nodes.literal("", "SPHINX_GITHUB_CHANGELOG_TOKEN")
+    par += nodes.Text(" environment variable or the ")
     par += nodes.literal("", "sphinx_github_changelog_token")
-    par += nodes.Text(" parameter is missing in the documentation configuration.")
+    par += nodes.Text(" parameter in ")
+    par += nodes.literal("", "conf.py")
+    par += nodes.Text(
+        ", or it can be automatically located from a configured git credential helper."
+    )
     result: List[nodes.Node] = [nodes.warning("", par)]
 
     if changelog_url:

sphinx_github_changelog/credentials.py

@@ -0,0 +1,81 @@
+"""
+Credential helpers for sphinx-github-changelog.
+
+Provides functions to obtain a GitHub token using environment variables,
+git credential helpers, or the GitHub CLI.
+"""
+
+import os
+import subprocess
+from contextlib import suppress
+from typing import Optional
+
+
+def get_token_from_env(host: str = "github.com") -> Optional[str]:
+    """Get a GitHub token from the SPHINX_GITHUB_CHANGELOG_TOKEN env var.
+
+    Return None if the environment variable is not set.
+    """
+    return os.environ.get("SPHINX_GITHUB_CHANGELOG_TOKEN")
+
+
+def is_github_token(token: str) -> bool:
+    """Check if the given string appears to be a GitHub token.
+
+    See
+    https://github.blog/changelog/2021-03-31-authentication-token-format-updates-are-generally-available/
+    for the prefixes that indicate a GitHub token.
+
+    As of 2025-05-08 the prefixes are `ghp_`, `gho_`, `ghu_`, and `ghs_`. We
+    use a generic check for `gh?_` to allow for future prefixes.
+    """
+    return token.startswith("gh") and token[3] == "_"
+
+
+def get_token_from_git_credential(host: str = "github.com") -> Optional[str]:
+    """
+    Get a GitHub access token using git's credential helper.
+
+    >>> token = get_token_from_git_credential('example.com')
+    >>> token is None or isinstance(token, str)
+    True
+    """
+    with suppress(subprocess.CalledProcessError, FileNotFoundError):
+        resp = subprocess.check_output(
+            ["git", "credential", "fill"],
+            input=f"protocol=https\nhost={host}\n",
+            text=True,
+        )
+        for ln in resp.splitlines():
+            key, eq, value = ln.partition("=")
+            if key == "password" and is_github_token(value):
+                return value
+    return None
+
+
+def get_token_from_gh_cli(host: str = "github.com") -> Optional[str]:
+    """Get a GitHub token using the GitHub CLI (gh auth token)."""
+    with suppress(subprocess.CalledProcessError, FileNotFoundError):
+        token = subprocess.check_output(
+            ["gh", "auth", "token", f"--hostname={host}"], text=True
+        ).strip()
+        if token:
+            return token
+    return None
+
+
+def get_github_token(host: str = "github.com") -> Optional[str]:
+    """
+    Try to obtain a GitHub token using several mechanisms in order.
+
+    1. Environment variable
+    2. git credential helper
+    3. gh CLI
+
+    Returns None if no token is found.
+    """
+    return (
+        get_token_from_env(host)
+        or get_token_from_git_credential(host)
+        or get_token_from_gh_cli(host)
+    )