Python documentation

There are a couple of options for creating documentation in Python, particularly Python that is hosted somewhere like Github, each with different advantages/disadvantages.

What I'm Looking For

In order of importance, I want the following out of my documentation system:

Barely Sufficient - First, following 10 Best practices for software engineering #5 (create barely-sufficient, source-centric documentation), documentation systems should require minimal effort (anything more than that, and the documentation will always be out of date and will require too much effort).

Room For Expansion - However, if I have a surge of benevolence, I want a documentation system that will allow me to explain stuff using diagrams and/or equations.

Pretty - Documentation should not look like a baboon.

Not Require Learning New Language/Toolchain/Build System - life is too short.

The Options

I considered the following options:

1. Epydocs
2. Pydoc
3. Docstrings
4. Sphinx
5. Github
6. Doxygen
7. Doxypy

The Winners

Epydoc

Epydoc creates Doxygen-esque output (win) using pydocs (also win), to accomplish source-centric documentation (see item 5 on 10_Best_Practices_for_Software_Engineering page).

Doxypypy

Wraps doxygen for python:

https://github.com/Feneric/doxypypy

Some Doxygen and Python notes:

http://meera-subbarao.blogspot.com/2010/08/doxygen-and-python.html

The Not-Winners, Not-Losers

Doxygen

Doxygen is a breeze for automatically-generated documentation, and is source-centric. It isn't the best, but it could certainly look worse.

GitHub

GitHub uses the Markdown markup language: very useful, looks great, hosted for free.

This makes it worth learning - but it doesn't give you the detailed documentation that you get with Doxygen or epydoc.

Also, if you are stuck with Svn this is kind of a dead end DUMP SVN ALREADY!!!

Apparently you can turn sphinx documentation into GitHub documentation, although Sphinx is not a winning documentation solution: http://daler.github.io/sphinxdoc-test/includeme.html

The Losers

PyDoc

You can run pydoc for a module with the name module_name by running pydoc module_name (the module should be on your Python path), but the HTML output of pydoc LITERALLY looks like a purple-assed baboon. There's pink, purple, orange, tan, gray, and everything else. The output is useful, but it looks like your documentation got hit by the Pee Wee's Playhouse truck and made a gory mess all over your browser.

Docstrings

Docstrings is the "default" way of documenting things in Python. It's the stuff that's printed when you type help(module) or print function.__doc__.

I can't say I've ever actually used the Docstrings of any software I've ever used. Some pedants will argue that you "shouldn't" use Docstrings for non-docstrings stuff, but they're like every other person on the internet saying you "shouldn't" do stuff.

There is a good explanation here: http://www.pythonforbeginners.com/basics/python-docstrings/

Sphinx

Sphinx is not automatically generated, by default - you must specifically instruct it to automatically generate documentation and include it. It makes your documentation much more customizable.

Sphinx is cumbersome and requires you to learn yet another markup language. Sphinx adds bold and italic and small text and big text all over the place, and doesn't look too great.

Miscellaneous

Doctest

Doctest is an interesting way to create tests within documentation - a good way to supplement documentation, not necessarily create standalone documentation:

http://docs.python.org/2/library/doctest.html