Посоветуйте альтернативу pydoc, чтобы по коду генерировать симпотичные доки в html. Беглый гуглинг показал, что таких инструментов тьма.

Я пользовался только epydoc.
Точнее я комментарии составляю в совместимом (на глаз :-) формате, но генерировать документы приходится крайне редко.
Возможны два типа разметки: свой или ReST (я использую первый, epydoc'овский).

..bw

Почему бы не использовать ту, которая используется на сайте Питона:
http://docs.python.org/py3k/about.html

Sphinx не очень подходит для комментирования кода, т.е. для “документации по коду”.
Для создания документации по пакету (рукописной), различных учебников и т.п., годится, но для документирования API, нет.

..bw

bw
Так Юрчек именно это и хочет получить: “чтобы по коду генерировать симпотичные доки в html”.

А базовые элементы: параграфы, отступы, - что в PEP257 (Docstring Conventions), что в PEP287 (reStructuredText Docstring Format) одинаковы.