Sphinx-Gallery
0.10.1
Versions v: stable
Versions
dev
stable

Using Sphinx Gallery

  • Getting Started with Sphinx-Gallery
  • How to structure your Python scripts for Sphinx-Gallery
  • Configuration
  • Who uses Sphinx-Gallery

Advanced usage and information

  • Advanced usage
  • Frequently Asked Questions
  • Sphinx-Gallery Utilities

Example galleries

  • Gallery of Examples
  • Notebook style example

API and developer reference

  • Sphinx-Gallery API Reference
  • Change Log
  • Fork Sphinx-Gallery on Github
Sphinx-Gallery
  • Docs »
  • Maintaining Sphinx Gallery

Maintaining Sphinx Gallery¶

This document contains tips for maintenance.

  • How to make a release

    • Check credentials and prerequisites

    • Prepare for release

    • Finalize the release

How to make a release¶

Check credentials and prerequisites¶

Sphinx Gallery is hosted on the pypi repository. To create a new release of Sphinx Gallery, you need to do these things: You should double-check a few things to make sure that you can create a new release for Sphinx Gallery.

  1. Ensure that you registered an account on the PyPI index.

  2. Ensure you have push access to the Sphinx Gallery pypi repository. Ask one of the Sphinx Gallery core developers if you do not.

  3. Install the GitHub Changelog Generator. This is a small tool written in Ruby to generate a markdown list of recent changes.

  4. Install the twine package. This is a package that helps you bundle and push new Python package distributions to pip.

Prepare for release¶

  1. Update CHANGES.rst

    1. Use github_changelog_generator to gather all merged pull requests and closed issues during the development cycle. You will likely need to generate a Github token as Github only allows 50 unauthenticated requests per hour. In the command below <version> is the current (not development) version of the package, e.g., 0.6.0. We do this because our failing discipline of writing in the CHANGES.rst all relevant changes, this helps our memory. It is a good idea to add appropriate labels (e.g., ‘BUG’) to issues and pull requests so they are categorized correctly in the CHANGES.rst generated.

      github_changelog_generator -u sphinx-gallery -p sphinx-gallery --since-tag=v<version> --token <your-40-digit-token>
      
    2. Edit CHANGELOG.md to look reasonable (it will be used later). It’s a good idea to add labels to issues and pull requests so github_changelog_generator can correctly categorize them in in the CHANGES.rst file generated.

    3. Propagate the relevant changes to CHANGES.rst. You can easily convert it RST with pandoc:

      pandoc CHANGELOG.md --wrap=none -o CHANGELOG.rst
      
  2. Build the docs cleanly

    Make sure to clean all and have a clean build. Double-check visually that everything looks right.

  3. Double check CIs

    Make sure CIs are green on the master branch.

  4. Update version

    Update the version in sphinx_gallery/__init__.py, which should end in .dev0. You should remove .dev0, and the numbers that remain will become the version for this release.

  5. Open a Pull Request that contains the two changes we’ve made above

    The version bump and the CHANGELOG update should be in the PR. Get somebody else to make sure all looks well, and merge this pull request.

Finalize the release¶

  1. Create the new release on PyPI

    • Build a source distribution:

      python setup.py sdist
      
    • Check the release:

      twine check dist/sphinx-gallery-<version>.tar.gz
      

      <version> should be the release version, e.g., 0.7.0.

    • Upload to PyPI:

      twine upload dist/sphinx-gallery-<version>.tar.gz
      

      Again, <version> should be the release version, e.g., 0.7.0.

    • Confirm that the new version of Sphinx Gallery is posted to pypi.

  2. Create a new release on GitHub

    • Go to the Draft a new release page.

    • The tag version is whatever the version is in __init__.py prepended with v. E.g., v0.7.0.

    • The release title is Release <tag-version>.

    • The description should contain the markdown changelog you generated above (in the CHANGELOG.md file).

    • Click Publish release when you are done.

  3. Now that the releases are complete, we need to switch the “master” branch back into a developer mode. Bump the Sphinx Gallery version number to the next minor (or major) release and append .dev0 to the end, and make a PR for this change.

  4. Celebrate! You’ve just released a new version of Sphinx Gallery!


© Copyright 2014-2022, Sphinx-gallery developers.

Built with Sphinx using a theme provided by Read the Docs.