Mac’s are just different enough it is hard to make this work. Sphinx generate documentation, but as usual, even with the vanilla Python 2.7 on every Mac, you have to install a lot of scaffolding, the easy way is to just type “sudo easy_install -U sphinx” but this uses non-SSL, so if you want SSL then you need to use get-pip:
- Install setup-tools (see http://peak.telecommunity.com/DevCenter/EasyInstall#mac-os-x-user-installation) for location which needs to be created. This assumes you want the packages to be per-user. The exact incantation is to download setup-tools.egg and then run “sh setup-tools.egg –install-dir=~/Library/Python/2.7/site-packages).
- Install pip which is the automated Python package installer, you have to do a curl download (curl -O https://raw.github.com/pypa/pip/master/contrib/get-pip.py
- Then run it as root, “sudo python get-pip.py”
- Install sphinx. Now you can get sphinx by “pip install sphinx” from the command line.
Another way to do this is with MacPorts, so you want to first figure out which python you are using
python --versionsudo port install py27-sphinx
This is to create a default index.rst and you need to populate it. The easy way is with the :glob: which will look for things. But this won’t install the pdf creator
sudo port install texlive texlive-extras sudo port install graphviz
This creates a gigantic pdf in _build/latex/*.pdf.
To make a single file, I couldn’t quite get rst2pdf to work and the last build was in 2012.
sudo pip install rst2pdf
To create a mini web site and to get a single pdf from it
- your new directory (Ideally, you fork a repository with github)
- Run “sphinx-quickstart”
- Edit the conf.py and add into the extensions [ ‘sphinx.ext.graphviz’ ]
- create your index.rst and start typing entering the right files in the .. toctruee
- To compile the RSTs into a website, run “sphinx-build -b html . ./html” would put all the rst’s at the current working directory and create html directory where the website is or more simply “make html” or “make latexpdf” to create a PDF
- To get a pdf that is a single page, start the browser and under the Mac, choose Print and then click on PDF and choose save as PDF.
