Building and Uploading Your Sphinx Docs to pypi

Building sphinx-build directly

First, create a doc directory at the root level and cd into that directory.

Sphinx’s quick start program will give you an option to make Makefile and a Windows .bat file. Personally, I find it easier just to call sphinx-build directly.

On linux:

$ /usr/bin/sphinx-build -b -E html source build\html

On windows:

$ C:\Python26\scripts\sphinx-build.exe -b -E html source build\html


The -E flag forces sphinx to always reread the files.

Building pdf document

To date, I’ve only built the pdf on a windows system.

On Windows, first you need to grab and install MiTek from which is used to convert tex to pdf.

On windows you would run a script like this from the doc directory:

C:\Python26\scripts\sphinx-build.exe -b latex source build\pdf
texify --clean --pdf build\pdf\an_example_pypi_project.tex

Here is the pdf An Example Pypi Project.


When using the pdf option, you often use the .. only:: html directive.

For example, the download link for the pdf does not make sense to be in the pdf itself, so you use:

:download:`An Example Pypi Project<docs/an_example_pypi_project.pdf>`

Directory Structure

This is not complete, but the basic outline of the directory structure, so far, is this:

|-- an_example_pypi_project
|   |--
|   |--
|   |--
|-- tests
|-- |--
|-- |--
|-- |--
|-- doc
|-- |-- source
|-- |-- build
|-- |-- |-- html
|-- |-- |-- pdf

Using Sphinx-PyPI-upload

There is a great package at which allows you to easily build and upload your docs using setuptools and your file.

To install, type:

$ easy_install sphinx-pypi-upload

Then, you’ll need to add a setup.cfg file to the directory that holds your file. The file looks like this:

source-dir = doc/source
build-dir  = doc/build
all_files  = 1

upload-dir = doc/build/html


To build using this tool, all you need to do is:

$ python build_sphinx

and you’re done.


Like before when uploading your eggs/source, you need to make sure your $HOME directory is set to where your .pypirc file lives.

Then you just type:

$ cd /var/local/wwww/pypi/HG_AN_EXAMPLE_PYPI_PROJECT
$ python upload_sphinx

On windows, I often just set the HOME variable directly. Here is a build and upload script sphinx.bat for windows:

set HOME=C:\Users\Owner\
cd C:\eclipse\workspace\HG_AN_EXAMPLE_PYPI_PROJECT
C:\Python26\python.exe build_sphinx
C:\Python26\python.exe upload_sphinx