[Gajim-devel] Gajim API docs [and thoughts on coding standards and testing]

[Mateusz Biliński]

On Fri, May 30, 2008 at 8:37 PM, Torsten Bronger
<bronger at physik.rwth-aachen.de> wrote:
> Stephan Erb writes:
>> [...]
>>
>> Epydoc seems to be really mighty. As far as I see we have do agree
>> on a documentation style. (if we agree to use epydoc)
>
> I strongly recommend using reStructuredText.  It may make a
> transition to Doxygen more difficult but as far as I can see, Epydoc
> offers everything one needs anyway.  I write my pet project with
> Epydoc+reST and the resulting documentation is superb.
>
>> Mateusz, can you tell if there is way for us to follow the python
>> styleguide [0] though we are using epydoc?
>
> Both standards are orthogonal as far as I can see.  Moreover, I
> believe reST is considered standard by the Python core team.

AFAIK (after small research), there is no way to make Epydoc work with
standard PyDoc syntax, so we'll have to give up existing docs and
rewrite it to syntax we decide to use.

After reading some docs, I think I opt for reST, as Torsten proposed.
It has all features of epytext and it's pretty much standard. In fact,
there's is, as Torsten wrote, some PEP on using reST in docstrings:
http://www.python.org/dev/peps/pep-0287/

So this solution sound promising. Syntax of reST in Epydoc can be found here:
http://epydoc.sourceforge.net/manual-othermarkup.html

-- 
Mateusz Biliński