We'll soon (~1-2 months) have a documentation system that renders HTML documentation from Python docstrings written with reStructuredText.

At one of the PCW hack sessions (with a large majority of non-DMLT DM members in attendance) we had unanimous agreement that we should start writing Python docstrings in this form now, instead of prefixing docstrings with a "!" to invoke Doxygen markup.

This will temporarily make HTML documentation for Python uglier (it will be rendered as reStructuredText source), but will eventually make it nicer, and it will make on-line Python docstrings modestly more readable (because reStructuredText source is more readable than Doxygen markup).

If other hack session work goes quickly and this RFC is accepted ahead of schedule, this could give us an opportunity to start this transition for existing code during the meeting.