First, create adoc directory at the root level andcd into thatdirectory.
Sphinx’s quick start program will give you an option to make Makefile anda Windows .bat file. Personally, I find it easier just to call sphinx-builddirectly.
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.
To date, I’ve only built the pdf on a windows system.
On Windows, first you need to grab and install MiTek fromhttp://miktex.org/which is used to convert tex to pdf.
On windows you would run a script like this from thedoc directory:
C:\Python26\scripts\sphinx-build.exe -b latex source build\pdftexify --clean --pdf build\pdf\an_example_pypi_project.tex
Here is the pdfAn 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 thepdf itself, so you use:
:download:`AnExamplePypiProject<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 athttp://pypi.python.org/pypi/Sphinx-PyPI-upload/0.2.1which allows you to easily build and upload your docs using setuptools and yoursetup.py file.
To install, type:
$ easy_install sphinx-pypi-upload
Then, you’ll need to add asetup.cfg file to the directory that holdsyoursetup.py file. The file looks like this:
[build_sphinx]source-dir=doc/sourcebuild-dir=doc/buildall_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$HOMEdirectory 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 theHOME variable directly. Here is a buildand upload scriptsphinx.bat for windows:
set HOME=C:\Users\Owner\cd C:\eclipse\workspace\HG_AN_EXAMPLE_PYPI_PROJECTC:\Python26\python.exe setup.py build_sphinxC:\Python26\python.exe setup.py upload_sphinxpause
Enter search terms or a module, class or function name.