Recently, I have been trying to write a project’s documentation with Sphinx. One important task is uploading the generated documentation to PyPI automatically, and there is a package just for that: Sphinx-PyPI-upload.

Although it’s said to support setuptools—which I don’t use, you can still use it with standard distutils as described in BuildDoc command from Sphinx.

If your setup.py uses setuptools or distribute packages, then the build_sphinx and upload_sphinx commands are automatically included in your setup.py. However, you wouldn’t need Sphinx-PyPI-upload, because setuptools comes with upload_docs command and it looks like doing the same job.

Since I prefer to stay with distutils, so the commands must be added manually:

from sphinx.setup_command import BuildDoc
from sphinx_pypi_upload import UploadDoc

setup_d = dict(
  # ...
  cmdclass={
    # ...
    'build_sphinx': BuildDoc,
    'upload_sphinx': UploadDoc,
    # ...
  },
  # ...
)

With the code above, one command can automatically pack the built documentation and upload to PyPI, just like the build and upload commands for the package’s distribution files.

I don’t actually use the build_sphinx command, but the Makefile generated by sphinx-quickstart, however it’s no harm to add the command in setup.py.

My project basically is a single-module package and that’s enough to tell me writing documentation better starts early.