Let sphinx use version from setup.py

Question

If I do sphinx-quickstart I get asked about the version of the project.

I want to avoid to have two places for the version of my project.

How to do this in the python packing world?

Answer 1

The easiest (and probably cleanest) way is to define __version__ for the __init__.py of your top-level package, and then import that package and read the version in both setup.py and your Sphinx project's conf.py.

So lets say your project is called myproject.

Move your current version out of setup.py, and make it a variable in myproject/__init__.py instead:

myproject/__init__.py:

# import foo
# ...

__version__ = '1.5'

Import myproject in your project's setup.py, and replace the hardcoded version with myproject.__version__:

setup.py:

from setuptools import setup
from myproject import __version__


project = "myproject"

setup(
    name=project,
    version=__version__,
    # ...
)

In your Sphinx project's conf.py, do the same. So edit the generated conf.py along these lines:

docs/conf.py:

from myproject import __version__

# ...

# The short X.Y version.
version = __version__
# The full version, including alpha/beta/rc tags.
release = version

For an example of a library that does this pretty much exactly like this, have a look at the requests module (__init__.py | setup.py | conf.py).

This will take care of the auto-generated texts where the project version is used (like the links to the front page of the documentation). If you want to use your version in specific custom places, you can use the rst_epilog directive to dynamically insert configuration values defined in conf.py.

Answer 2

Maybe an even cleaner option is to actually build sphinx from the setup.py command as described in http://www.sphinx-doc.org/en/master/setuptools.html:

setup.py

# this is only necessary when not using setuptools/distribute
from sphinx.setup_command import BuildDoc
cmdclass = {'build_sphinx': BuildDoc}

name = 'My project'
version = '1.2'
release = '1.2.0'
setup(
    name=name,
    author='Bernard Montgomery',
    version=release,
    cmdclass=cmdclass,
    # these are optional and override conf.py settings
    command_options={
        'build_sphinx': {
            'project': ('setup.py', name),
            'version': ('setup.py', version),
            'release': ('setup.py', release),
            'source_dir': ('setup.py', 'doc')}},
)

Then build documentation using

$ python setup.py build_sphinx

Benefits:

• Makes setup.py the single source of version number
• Avoids having to make packages out of your project folders unnecessarily

Answer 3

You could have a look at bumpversion module:

"A small command line tool to simplify releasing software by updating all version strings in your source code by the correct increment"

You may use a configuration file .bumpversion.cfg for complex multi-file operations.

Answer 4

Another way is integrating setuptools_scm in your project. This way you can

from setuptools_scm import get_version

version = get_version()

in your conf.py

Answer 5

Here is a straightforward solution, ironically from the setuptools_scm PyPI page:

# contents of docs/conf.py
from importlib.metadata import version
release = version('myproject')
# for example take major/minor
version = '.'.join(release.split('.')[:2])

Here is their explanation why it is discouraged to use their package from Sphinx:

The underlying reason is, that services like Read the Docs sometimes change the working directory for good reasons and using the installed metadata prevents using needless volatile data there.

Answer 6

Extract Information from pyproject.toml

If you use a pyproject.toml you could also parse it in the conf.py with tomli or use the equivalent tomllib when you are on python ^3.11.
Like this you can extract the information from the pyproject.toml and use it in your sphinx documentation configuration.

Here a short incomplete example using tomli, assuming conf.py
is located at <project-root>/docs/source/conf.py:

# conf.py

import tomli
with open("../../pyproject.toml", "rb") as f:
    toml = tomli.load(f)

# -- Project information -----------------------------------------------------

pyproject = toml["tool"]["poetry"]

project = pyproject["name"]
version = pyproject["version"]
release = pyproject["version"]

copyright = ...
author = ...

# and the rest of the configuration