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

Note

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 http://miktex.org/ 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.

Note

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:

some_root_dir/
|-- README
|-- setup.py
|-- an_example_pypi_project
|   |-- __init__.py
|   |-- useful_1.py
|   |-- useful_2.py
|-- tests
|-- |-- __init__.py
|-- |-- runall.py
|-- |-- test0.py
|-- doc
|-- |-- source
|-- |-- build
|-- |-- |-- html
|-- |-- |-- pdf

Using Sphinx-PyPI-upload

There is a great package at http://pypi.python.org/pypi/Sphinx-PyPI-upload/0.2.1 which allows you to easily build and upload your docs using setuptools and your setup.py 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 setup.py file. The file looks like this:

[build_sphinx]
source-dir = doc/source
build-dir  = doc/build
all_files  = 1

[upload_sphinx]
upload-dir = doc/build/html

Building

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

$ python setup.py build_sphinx

and you’re done.

Uploading

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 setup.py 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 setup.py build_sphinx
C:\Python26\python.exe setup.py upload_sphinx
pause