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 (read: I am lazy) - First, following 10 Best practices for software engineering #5 (create barely-sufficient, source-centric documentation), I want a documentation system that requires 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 purple-assed baboon.

Not Require Me To Learn Yet Another Markup Language/Toolchain/Build System (read: lazy) - Unless it makes my documentation look really sexy, and there's absolutely no other way to do it, I don't want to have to learn yet another markup language, toolchain, and/or build system.

The Options

I considered the following options:

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

The Winners

Doxygen

Doxygen is a breeze for automatically-generated documentation, and is source-centric. It isn't the prettiest, but it isn't a purple-assed baboon, either.

The Not-Winners, Not-Losers

GitHub

GitHub uses the Markdown markup language, which is actually pretty useful, and it looks really good, so it is worth learning. But it still isn't (necessarily) worth writing all of your documentation in GitHub's markup language.

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, except when you specifically instruct it to automatically generate documentation.

Sphinx is cumbersome and requires you to learn yet another markup language.

Sphinx is ugly as hell (the automatically generated stuff, anyway), adding bold and italic and small text and big text like a drunken sailor with a font palate.

My notes on Sphinx are at the Sphinx page.

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