Using Setuptools with Sphinx to Automatically Generate Documentation

Setuptools is a toolkit for building and publishing Python packages. It offers powerful commands and libraries that simplify creating, building, and distributing Python software.

Key features include managing dependencies through the setup.py file, packaging source code and resources, installing scripts and executables, providing a suite of command‑line tools for building, installing, upgrading, and removing packages, and supporting automatic documentation generation when used together with external tools such as Sphinx.

Basic usage example

1. Install Sphinx:

pip install sphinx

2. In the project root, create a docs folder and initialise Sphinx:

cd my_project
mkdir docs
cd docs
sphinx-quickstart

3. Write documentation in docs/source using reStructuredText or Markdown, configure docs/source/conf.py , and then modify setup.py to run Sphinx before the package is built:

from setuptools import setup
from setuptools.command.build_py import build_py

class CustomBuildCommand(build_py):
    def run(self):
        # Generate documentation before building the package
        import subprocess
        subprocess.call('sphinx-build -b html docs/source docs/build', shell=True)
        # Continue with the normal build process
        build_py.run(self)

setup(
    # ... other setup arguments ...
    cmdclass={
        'build_py': CustomBuildCommand,
    }
)

4. Build the package with python setup.py build ; the documentation will be generated automatically and placed in docs/build .

Conclusion

By following these steps you can combine Setuptools and Sphinx to automatically generate documentation and include it in the built package, with the example providing a basic configuration that can be extended to meet specific project needs.