Ok, so I'm think I'm in sphinx-love. I've needed to really begin a largish documentation project for a code base I own and drive (omgmanagerspeak) and since I'd rather not completely rely on API docs, and I have exposure to sphinx courtesy of python-core work, I chose you sphinx-a-chu! Sphinx really is awesome. I started just chugging through the docs, and ended up pulling from tip (via mercurial) and using the latest version for the theme support Georg added recently.
Rather than rehash the basics, I'll simple explain my setup, and why I love it - starting with the output from sphinx-quickstart which kicks out a makefile for you, I immediately turned on the 'sphinx.ext.autodoc' and 'sphinx.ext.doctest' extensions - the former allows you to tell sphinx (in your rst file) to delegate the documentation for this class/method/etc to the API docs, and the latter allows you to pass the examples/snippets you will have through doctest.
These two things make writing/testing the docs awesome - but it gets more awesome.
With sphinx, you can run make html to run your build, part of which is the verification of your .rst syntax. I added a target to the Makefile to run the doctests:
doctest: mkdir -p build/doctests $(SPHINXBUILD) -b doctest source build/doctests @echo @echo "Doctests passed"
This means I can run "make doctests html" and I get everything I want. Hooray!
But wait.. I don't want to have to edit, build, and open the html to review/read it - we can make this smarter, faster.
So, loaded up Bruno Bord's tdaemon and hacked it up so that I could pass it in a custom command (I added a sphinx argument), so after I point it at my doc/source/ directory - any time I hit save the "make doctest html" target runs.
This is nice - it's instant build/feedback. I coupled this with the simple "python -m SimpleHTTPServer" running in the build/html/ directory of the docs and leave my browser pointed at localhost:8000.
All I need to do is hit save, and provided I haven't failboated the tests, I can just hit refresh and see things immediately.
I'm probably going to hack tdaemon up a bit to either accept a command series, or allow arbitrary commands so I can remove the hardcoded sphinx logic I added, and possibly add the capability of watching multiple directories (and supporting custom (different) commands to each.
This way, I could say "tdaemon --dir1=sphinxsource --cmd="make doctests html" --dir2=pythondir --cmd="nosetests -s -v". This way if I hit save on any file I'm working on I get this same feedback loop.
I can hack this so it auto-tests/deploys a Django application as well (on changes) to my local sandbox as well. Just something neat, that's working well for me. Additionally, I want to add some intelligence that in the case of a failure, the log file is automatically opened in the editor of my choice via the OS/X open command.
I should add, that I also hacked tdaemon to modify my PYTHONPATH to add the project I'm hacking on so I don't need to install/deploy it for the API integration in sphinx to work. This allows me to have this type of setup on a per-branch basis.