Proposal: Adopt "Sphinx" as PySoy docstring format

[ArcRiley]

Python has adopted Sphinx as the standard documentation format starting with Python 2.6 (and 3.0).

Sphinx uses ReST formatting and offers many features over epydoc such as pygments code highlighting. By using Sphinx we can also remain as similar to Python core as possible.

This must be decided as a Trac plugin needs to be written for our standard and the codebase needs to be fully documented before beta-3 release.

Please comment to this ticket with discussion and (dis)support for this proposal.

[JonNeal]

Seems like a good idea, because being supported by Python it will have a ton of support. Might there already be a plugin for it that someone else has written?

Other than that, I say all for it because it looks like it could offer quite a few advantages.

[ArcRiley]

The largest advantage I've found in Sphinx is that it's more than just API docs (as (e)pydoc is)

You write the docs as separate ReST files (ie, in /docs/src), which can include via Sphinx extensions to ReST links and included strings from the package's pydocs, and output html/pdf/etc.

This can make PySoy much easier to learn and include tutorials/etc. This besides that Python itself is now using Sphinx for it's own documentation (and many other Python-based projects).