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.
$ /usr/bin/sphinx-build -b -E html source build\html
$ C:\Python26\scripts\sphinx-build.exe -b -E html source build\html
The -E flag forces sphinx to always reread the files.
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.
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>`
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
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
To build using this tool, all you need to do is:
$ python setup.py 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 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