Sphinx Github Changelog: Build a sphinx changelog from GitHub Releases

Sphinx-github-changelog is a Sphinx plugin that builds a changelog section based on a repository’s GitHub Releases content.

How ? (the short version)

In your Sphinx documentation conf.py:

extensions = [
    ...,  # your other extensions
    "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:

.. changelog::
    :changelog-url: https://your-project.readthedocs.io/en/stable/#changelog
    :github: https://github.com/you/your-project/releases/
    :pypi: https://pypi.org/project/your-project/

See the end result for this project on ReadTheDocs.

Why ?

On the way to continuous delivery, it’s important to be able to release easily. One of the criteria for easy releases is that the release doesn’t require a commit and a Pull Request. Release Pull Requests usually include 2 parts:

• Changing the version
• Updating the changelog (if you keep a changelog, let’s assume you do)

Commitless releases need a way to store the version and the changelog, as close as possible to the code, but actually not in the code.

Setting aside the “version” question, sphinx-github-changelog aims at providing a good way of managing the “changelog” part:

The best solution we’ve found so far for the changelog is to store it in the body of GitHub Releases. That’s very practical for maintainers, but it may not be the first place people will look for it. As far as we’ve seen, people expect the changelog to be:

• in the repo, in CHANGELOG.rst,
• in the documentation.

Having the changelog in CHANGELOG.rst causes a few problems:

• Either each PR adds its single line of changelog, but:

  • you’ll most probably run into countless merge conflicts,
  • the changelog won’t tell you which contribution was part of which release

  This reduces the interest for the whole thing.

• Or your changelog is edited at release time. Maybe you’re using towncrier for fragment-based changelog, but you’re not doing commitless releases anymore. You could imagine that the release commit is done by your CI, but this can quickly become annoying, especially if you require Pull Requests.

But there is another way. Instead of providing the changelog, the CHANGELOG.rst file can hold a link to the changelog. This makes things much easier. sphinx-github-changelog encourages you to do that.

A complete toolbelt

Alongside sphinx-github-changelog, we suggest a few tools that play nice together:

• setuptools-scm will compute your version in setup.py based on git tags.
• release-drafter will keep a “Draft release” updated as you merge Pull Requests to your repository, so you just have to slightly adjust the release body, and create a tag.
• Any Continuous Integration solution should be able to listen to new tags, and build and upload distributions to PyPI. Don’t forget to use PyPI API tokens!
• And ReadTheDocs to host your built documentation, of course.

If you’re using all the tools above, then releasing is simple as proof-reading the draft GitHub Release and press “Publish Release”. That’s it.

Reference documentation

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

Directive

.. changelog::
    :changelog-url: https://your-project.readthedocs.io/en/stable/changelog.html
    :github: https://github.com/you/your-project/releases/
    :pypi: https://pypi.org/project/your-project/

Attributes

• github (required): URL to the releases page of the repository.
• 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)
• pypi (optional): URL to the PyPI page of the repository. This allows the changelog to display links to each PyPI release.

You’ll notice that each parameter here is not requested in the simplest form but as very specific URLs from which the program extracts the needed information. This is done on purpose. If people browse the unbuilt version of your documentation (e.g. on GitHub or PyPI directly), they’ll still be presented with links to the pages that contain the information they will need, instead of unhelping directives.

Changelog

This documentation itself is “drinking its own champagne”: it uses sphinx-github-changelog. Here’s what it looks like.

1.2.1

Released on 2023-02-15 - GitHub - PyPI

• fix error message when PyPI url is incorrect (#105)
• [pre-commit.ci] pre-commit autoupdate (#103, #102, #99, #97, #96, #95, #93, #92, #91, #90, #88, #86, #85, #84, #83, #82, #81, #80, #79, #78, #77, #76, #75, #74, #73, #69, #68, #67, #66, #65, #64, #63, #62, #61, #60, #59)
• Bump certifi from 2022.6.15 to 2022.12.7 (#94)
• Update .pre-commit-config.yaml (#72)

Kudos:

@bj00rn

1.2.0

Released on 2022-01-21 - GitHub - PyPI

• Unpin deps (#58)
• [pre-commit.ci] pre-commit autoupdate (#56)
• [pre-commit.ci] pre-commit autoupdate (#55)

1.1.0

Released on 2022-01-03 - GitHub - PyPI

• [pre-commit.ci] pre-commit autoupdate (#54, #52, #51, #50, #49, #48, #47, #46, #45, #44, #42, #41, #40, #39, #37, #36, #35, #34, #32, #28, #27, #26, #25, #24, #22, #21, #20)
• Add support for Sphinx v4 (#53)
• Replace codecov with coverage-comment (#43)
• Fix CI python-version (#38)
• Fix mypy (#31)
• Delete unused requirements.txt (#23)

Kudos:

@mondeja

1.0.8

Released on 2021-04-17 - GitHub - PyPI

Miscellaneous

• Badges (#19)

Kudos:

@ewjoachim

1.0.7

Released on 2021-04-17 - GitHub - PyPI

Bug Fixes

• Readthedocs fail on warning (#18)

Kudos:

@ewjoachim

1.0.6

Released on 2021-04-17 - GitHub - PyPI

Miscellaneous

• Iterate on CI again (#16)
• ReadTheDocs (#17)

Kudos:

@ewjoachim

1.0.5

Released on 2021-04-17 - GitHub - PyPI

Bug Fixes

• publish restores the file (#12)

Miscellaneous

• iterate on CI (#14)
• Improve cache & publish (#13)
• pre-commit.ci is now responsible for the linting (#15)

Kudos:

@ewjoachim and @pre-commit-ci[bot]

1.0.4: Add missing dependency dunamai

Released on 2021-04-16 - GitHub - PyPI

Bug Fixes

• Add dunamai (#11)

Kudos:

@ewjoachim

1.0.3: Redo boilerplate, fix crash when there are draft releases

Released on 2021-04-16 - GitHub - PyPI

Bug Fixes

• Fixes #8 : node_for_release should not return [] (#9)

Miscellaneous

• Redo Boilerplate (#10)
• Adding "Framework :: Sphinx :: Extension" classifier (#7)

Kudos:

@jeriox

1.0.2: Fix for Release Drafts

Released on 2020-07-31 - GitHub - PyPI

Bug Fixes

• Fix crash in case of draft release (#6)

Misc

• Check lint in CI (#5)

1.0.1: Travis PyPI deployment

Released on 2020-07-27 - GitHub - PyPI

• Add PyPI token to Travis (#4)

1.0.0: A fresh start

Released on 2020-07-27 - GitHub - PyPI

Features

• Initial code (#2)

Bug Fixes

• Main branch is actually called main (#3)

---

Test

The following text is just to test the changelog markup

A title

• #1 by @ewjoachim
• example.com
• unordered list
• ordered list
  1. a
  2. b
• bold, italics, both, strikethrough

Other links

• Code of Conduct
• Contributing