About a year ago, we started out doing Python development with simple rst2htmldocuments for requirements, design, etc. In the code, we had comments that used epydoc with the epytextmarkup language.
No, it wasn’t confusing. Free-text documents (requirements, architecture, design, test plans, etc.) are easy and fun to write in RST. Just write. Leave the formatting to someone else. A little semantic markup doesn’t hurt, but you don’t spend hours with MS-Word trying to disentangle your bullets and your numbering.
Adding comments to code in epytext was pretty easy, also.
Then I discovered Sphinx. Sphinx can add module documentation to a document tree very elegantly. Further, Sphinx can pull in RST-formatted module comment strings. Very nice.
Except, of course, we have hundreds of modules in epytext. Today, I started tracking down all of the 150+ modules without proper document strings in RST notation. Hopefully, this time tomorrow, I’ll have a much, much better -- and internally consistent -- set of documentation.