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 .. only:: html Here is the pdf :download:`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``` 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