Sphinx Github Changelog: Build a sphinx changelog from GitHub Releases
======================================================================
.. image:: https://img.shields.io/pypi/v/sphinx-github-changelog?logo=pypi&logoColor=white
:target: https://pypi.org/pypi/sphinx-github-changelog
:alt: Deployed to PyPI
.. image:: https://img.shields.io/pypi/pyversions/sphinx-github-changelog?logo=pypi&logoColor=white
:target: https://pypi.org/pypi/sphinx-github-changelog
:alt: Deployed to PyPI
.. image:: https://img.shields.io/github/stars/ewjoachim/sphinx-github-changelog?logo=github
:target: https://github.com/ewjoachim/sphinx-github-changelog/
:alt: GitHub Repository
.. image:: https://img.shields.io/github/actions/workflow/status/ewjoachim/sphinx-github-changelog/ci.yml?logo=github&branch=main
:target: https://github.com/ewjoachim/sphinx-github-changelog/actions?workflow=CI
:alt: Continuous Integration
.. image:: https://img.shields.io/readthedocs/sphinx-github-changelog?logo=read-the-docs&logoColor=white
:target: http://sphinx-github-changelog.readthedocs.io/en/latest/?badge=latest
:alt: Documentation
.. image:: https://img.shields.io/endpoint?logo=codecov&logoColor=white&url=https://raw.githubusercontent.com/wiki/ewjoachim/sphinx-github-changelog/coverage-comment-badge.json
:target: https://github.com/marketplace/actions/coverage-comment
:alt: Coverage
.. image:: https://img.shields.io/github/license/ewjoachim/sphinx-github-changelog?logo=open-source-initiative&logoColor=white
:target: https://github.com/ewjoachim/sphinx-github-changelog/blob/master/LICENSE
:alt: MIT License
.. image:: https://img.shields.io/badge/Contributor%20Covenant-v1.4%20adopted-ff69b4.svg
:target: https://github.com/ewjoachim/sphinx-github-changelog/blob/master/CODE_OF_CONDUCT.md
:alt: Contributor Covenant
Sphinx-github-changelog is a Sphinx_ plugin that builds a changelog section based on
a repository's `GitHub Releases`_ content.
.. _Sphinx: https://www.sphinx-doc.org/en/master/
.. _`GitHub Releases`: https://docs.github.com/en/github/administering-a-repository/about-releases
How ? (the short version)
=========================
In your Sphinx documentation ``conf.py``:
.. code-block:: python
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:
.. code-block:: restructuredtext
.. 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__.
.. __: https://sphinx-github-changelog.readthedocs.io/en/stable/#changelog
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.
.. _`setuptools-scm`: https://pypi.org/project/setuptools-scm/
.. _`release-drafter`: https://help.github.com/en/github/administering-a-repository/about-releases
.. _towncrier: https://pypi.org/project/towncrier/
.. _`PyPI API tokens`: https://pypi.org/help/#token
.. _ReadTheDocs: https://readthedocs.org/
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).
- ``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.
- ``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.
.. _ReadTheDocs: https://readthedocs.org/
Directive
---------
.. code-block:: restructuredtext
.. 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.
.. Below this line is content specific to GitHub / PyPI that will not appear in the
built doc.
.. end-of-index-doc
Check out the built version!
============================
This Readme is also built as a Sphinx documentation, and it includes the changelog.
Interested to see how it looks? Check it out on `our ReadTheDocs space`_.
.. _`our ReadTheDocs space`: https://sphinx-github-changelog.readthedocs.io/en/stable
If you encounter a bug, or want to get in touch, you're always welcome to open a
ticket_.
.. _ticket: https://github.com/peopledoc/sphinx-github-changelog/issues/new
Other links
===========
- `Code of Conduct <CODE_OF_CONDUCT.rst>`_.
- `License <LICENCE.rst>`_.
- `Contributing Guidelines <CONTRIBUTING.rst>`_.
Raw data
{
"_id": null,
"home_page": "https://sphinx-github-changelog.readthedocs.io/en/latest/",
"name": "sphinx-github-changelog",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "sphinx, github, releases, changelog",
"author": "Joachim Jablon",
"author_email": "ewjoachim@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/8f/21/90bc47a6cdfff2e37bc233754f6662808975528a73dab0bf6a5215eeb2a5/sphinx_github_changelog-1.4.0.tar.gz",
"platform": null,
"description": "Sphinx Github Changelog: Build a sphinx changelog from GitHub Releases\n======================================================================\n\n.. image:: https://img.shields.io/pypi/v/sphinx-github-changelog?logo=pypi&logoColor=white\n :target: https://pypi.org/pypi/sphinx-github-changelog\n :alt: Deployed to PyPI\n\n.. image:: https://img.shields.io/pypi/pyversions/sphinx-github-changelog?logo=pypi&logoColor=white\n :target: https://pypi.org/pypi/sphinx-github-changelog\n :alt: Deployed to PyPI\n\n.. image:: https://img.shields.io/github/stars/ewjoachim/sphinx-github-changelog?logo=github\n :target: https://github.com/ewjoachim/sphinx-github-changelog/\n :alt: GitHub Repository\n\n.. image:: https://img.shields.io/github/actions/workflow/status/ewjoachim/sphinx-github-changelog/ci.yml?logo=github&branch=main\n :target: https://github.com/ewjoachim/sphinx-github-changelog/actions?workflow=CI\n :alt: Continuous Integration\n\n.. image:: https://img.shields.io/readthedocs/sphinx-github-changelog?logo=read-the-docs&logoColor=white\n :target: http://sphinx-github-changelog.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation\n\n.. image:: https://img.shields.io/endpoint?logo=codecov&logoColor=white&url=https://raw.githubusercontent.com/wiki/ewjoachim/sphinx-github-changelog/coverage-comment-badge.json\n :target: https://github.com/marketplace/actions/coverage-comment\n :alt: Coverage\n\n.. image:: https://img.shields.io/github/license/ewjoachim/sphinx-github-changelog?logo=open-source-initiative&logoColor=white\n :target: https://github.com/ewjoachim/sphinx-github-changelog/blob/master/LICENSE\n :alt: MIT License\n\n.. image:: https://img.shields.io/badge/Contributor%20Covenant-v1.4%20adopted-ff69b4.svg\n :target: https://github.com/ewjoachim/sphinx-github-changelog/blob/master/CODE_OF_CONDUCT.md\n :alt: Contributor Covenant\n\nSphinx-github-changelog is a Sphinx_ plugin that builds a changelog section based on\na repository's `GitHub Releases`_ content.\n\n.. _Sphinx: https://www.sphinx-doc.org/en/master/\n.. _`GitHub Releases`: https://docs.github.com/en/github/administering-a-repository/about-releases\n\nHow ? (the short version)\n=========================\n\nIn your Sphinx documentation ``conf.py``:\n\n.. code-block:: python\n\n extensions = [\n ..., # your other extensions\n \"sphinx_github_changelog\",\n ]\n\n # Provide a GitHub API token:\n # Pass the SPHINX_GITHUB_CHANGELOG_TOKEN environment variable to your build\n # OR\n # You can retrieve your token any other way you want, but of course, please\n # don't commit secrets to git, especially on a public repository\n sphinx_github_changelog_token = ...\n\nIn your documentation:\n\n.. code-block:: restructuredtext\n\n .. changelog::\n :changelog-url: https://your-project.readthedocs.io/en/stable/#changelog\n :github: https://github.com/you/your-project/releases/\n :pypi: https://pypi.org/project/your-project/\n\n\nSee the end result for this project on ReadTheDocs__.\n\n.. __: https://sphinx-github-changelog.readthedocs.io/en/stable/#changelog\n\nWhy ?\n=====\n\nOn the way to continuous delivery, it's important to be able to release easily.\nOne of the criteria for easy releases is that the release doesn't require a commit and\na Pull Request. Release Pull Requests usually include 2 parts:\n\n- Changing the version\n- Updating the changelog (if you keep a changelog, let's assume you do)\n\nCommitless releases need a way to store the version and the changelog, as close as\npossible to the code, but actually **not in** the code.\n\nSetting aside the \"version\" question, ``sphinx-github-changelog`` aims at providing\na good way of managing the \"changelog\" part:\n\nThe best solution we've found so far for the changelog is to store it in the body of\n`GitHub Releases`_. That's very practical for maintainers, but it may not be the first\nplace people will look for it. As far as we've seen, people expect the changelog to\nbe:\n\n- in the repo, in ``CHANGELOG.rst``,\n- in the documentation.\n\nHaving the changelog in ``CHANGELOG.rst`` causes a few problems:\n\n- Either each PR adds its single line of changelog, but:\n\n - you'll most probably run into countless merge conflicts,\n - the changelog won't tell you which contribution was part of which release\n\n This reduces the interest for the whole thing.\n\n- Or your changelog is edited at release time. Maybe you're using towncrier_ for\n fragment-based changelog, but you're not doing commitless releases anymore. You could\n imagine that the release commit is done by your CI, but this can quickly become\n annoying, especially if you require Pull Requests.\n\nBut there is another way. Instead of providing the changelog, the ``CHANGELOG.rst``\nfile can hold a *link* to the changelog. This makes things much easier.\n``sphinx-github-changelog`` encourages you to do that.\n\nA complete toolbelt\n-------------------\n\nAlongside ``sphinx-github-changelog``, we suggest a few tools that play nice together:\n\n- `setuptools-scm`_ will compute your version in ``setup.py`` based on git tags.\n- `release-drafter`_ will keep a \"Draft release\" updated as you merge Pull Requests to\n your repository, so you just have to slightly adjust the release body, and create a\n tag.\n- Any Continuous Integration solution should be able to listen to new tags, and build\n and upload distributions to PyPI. Don't forget to use `PyPI API tokens`_!\n- And ReadTheDocs_ to host your built documentation, of course.\n\n.. _`setuptools-scm`: https://pypi.org/project/setuptools-scm/\n.. _`release-drafter`: https://help.github.com/en/github/administering-a-repository/about-releases\n.. _towncrier: https://pypi.org/project/towncrier/\n.. _`PyPI API tokens`: https://pypi.org/help/#token\n.. _ReadTheDocs: https://readthedocs.org/\n\nIf you're using all the tools above, then releasing is simple as proof-reading the\ndraft GitHub Release and press \"Publish Release\". That's it.\n\nReference documentation\n=======================\n\nExtension options (``conf.py``)\n-------------------------------\n\n- ``sphinx_github_changelog_token``: GitHub API token.\n If the repository is public, the token doesn't need any special access (you\n can uncheck eveything). If the repository is private, you'll need to give\n your token enough access to read the releases. Defaults to the value of the\n environment variable ``SPHINX_GITHUB_CHANGELOG_TOKEN``. If no value is\n provided, the build will still pass but the changelog will not be built, and\n a link to the ``changelog-url`` will be displayed (if provided).\n\n- ``sphinx_github_changelog_root_repo`` (optional): Root url to the repository,\n defaults to \"https://github.com/\". Useful if you're using a self-hosted GitHub\n instance.\n\n- ``sphinx_github_changelog_graphql_url`` (optional): Url to graphql api, defaults\n to \"https://api.github.com/graphql\". Useful if you're using a self-hosted GitHub\n instance.\n\n.. _ReadTheDocs: https://readthedocs.org/\n\nDirective\n---------\n\n.. code-block:: restructuredtext\n\n .. changelog::\n :changelog-url: https://your-project.readthedocs.io/en/stable/changelog.html\n :github: https://github.com/you/your-project/releases/\n :pypi: https://pypi.org/project/your-project/\n\nAttributes\n~~~~~~~~~~\n\n- ``github`` (**required**): URL to the releases page of the repository.\n- ``changelog-url`` (optional): URL to the built version of your changelog.\n ``sphinx-github-changelog`` will display a link to your built changelog if the GitHub\n token is not provided (hopefully, this does not happen in your built documentation)\n- ``pypi`` (optional): URL to the PyPI page of the repository. This allows the changelog\n to display links to each PyPI release.\n\nYou'll notice that each parameter here is not requested in the simplest form but as\nvery specific URLs from which the program extracts the needed information. This is\ndone on purpose. If people browse the unbuilt version of your documentation\n(e.g. on GitHub or PyPI directly), they'll still be presented with links to the pages\nthat contain the information they will need, instead of unhelping directives.\n\n.. Below this line is content specific to GitHub / PyPI that will not appear in the\n built doc.\n.. end-of-index-doc\n\nCheck out the built version!\n============================\n\nThis Readme is also built as a Sphinx documentation, and it includes the changelog.\nInterested to see how it looks? Check it out on `our ReadTheDocs space`_.\n\n.. _`our ReadTheDocs space`: https://sphinx-github-changelog.readthedocs.io/en/stable\n\nIf you encounter a bug, or want to get in touch, you're always welcome to open a\nticket_.\n\n.. _ticket: https://github.com/peopledoc/sphinx-github-changelog/issues/new\n\nOther links\n===========\n\n- `Code of Conduct <CODE_OF_CONDUCT.rst>`_.\n- `License <LICENCE.rst>`_.\n- `Contributing Guidelines <CONTRIBUTING.rst>`_.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Build a sphinx changelog from GitHub Releases",
"version": "1.4.0",
"project_urls": {
"Documentation": "https://sphinx-github-changelog.readthedocs.io/en/latest/",
"Homepage": "https://sphinx-github-changelog.readthedocs.io/en/latest/",
"Repository": "https://github.com/ewjoachim/sphinx-github-changelog"
},
"split_keywords": [
"sphinx",
" github",
" releases",
" changelog"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0307a669a23f47803ad12e620b68b761bf7bf32fd9f293c5846fda8f3893d706",
"md5": "cf7537d1c90ed4196eaa4b89c8cd6341",
"sha256": "cdf2099ea3e4587ae8637be7ba609738bfdeca4bd80c5df6fc45046735ae5c2f"
},
"downloads": -1,
"filename": "sphinx_github_changelog-1.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cf7537d1c90ed4196eaa4b89c8cd6341",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 8513,
"upload_time": "2024-08-09T16:08:34",
"upload_time_iso_8601": "2024-08-09T16:08:34.374766Z",
"url": "https://files.pythonhosted.org/packages/03/07/a669a23f47803ad12e620b68b761bf7bf32fd9f293c5846fda8f3893d706/sphinx_github_changelog-1.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8f2190bc47a6cdfff2e37bc233754f6662808975528a73dab0bf6a5215eeb2a5",
"md5": "1a8c07c002d789b614f046dec63a193c",
"sha256": "204745e93a1f280e4664977b5fee526b0a011c92ca19c304bd01fd641ddb6393"
},
"downloads": -1,
"filename": "sphinx_github_changelog-1.4.0.tar.gz",
"has_sig": false,
"md5_digest": "1a8c07c002d789b614f046dec63a193c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 7583,
"upload_time": "2024-08-09T16:08:36",
"upload_time_iso_8601": "2024-08-09T16:08:36.116628Z",
"url": "https://files.pythonhosted.org/packages/8f/21/90bc47a6cdfff2e37bc233754f6662808975528a73dab0bf6a5215eeb2a5/sphinx_github_changelog-1.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-09 16:08:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ewjoachim",
"github_project": "sphinx-github-changelog",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphinx-github-changelog"
}
JSON
