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

Stephan Erb steve-e at h3c.de
Fri May 30 19:52:44 CEST 2008


generating documentation is always a good idea :-)

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)

Mateusz, can you tell if there is way for us to follow the python
styleguide [0] though we are using epydoc? 

Best Regards,

[0] http://www.python.org/dev/peps/pep-0257/

On Fri, 2008-05-30 at 14:45 +0200, Mateusz Biliński wrote:
> Hi all.
> I'm organizing my development environment for GSoC (and of course
> coding in parallel ;) ), so basically what I do is:
> 1. Writing code.
> As the base I use these coding standards:
> http://trac.gajim.org/wiki/CodingStandards
> Although, I not necessarily agree with all statements [i.e. max length
> of line equal to 80 chars (pretty 'oldish' in modern times, 100 or
> even more would be probably more reasonable here )] but I'll try to
> use them to keep code consistent.
> 2. Writing tests.
> bct has created new directory and already put some testing files in
> there for sessions. I've written some simple test file for
> PluginManager and probably I'll commit it to my branch very soon.
> It would be great to write standards here, too, and/or some kind of
> common module (with 'init' function). In example, I use the same code
> as bct to update paths (which is required to tests work properly from
> this new 'test/' directory). So, this 'paths updating' would be our
> common code for starters. It's not much, but maybe later we'll find
> more common code to put there.
> 3. Documenting code [aka 'API docs']
> I haven't found any official API docs for Gajim, so I've started
> generating them on my own. Here are basic effects:
> http://kernel.agh.edu.pl/~vardo/gajim/apidocs/
> Maybe it doesn't look pretty, but is very handy and we can fine-tune
> it (CSS is our friend).
> The biggest advantage here is that we see what is NOT documented.
> There's also source code browsing. Imports of modules are also there.
> So this may help on generating UML diagrams and other documents
> related to Gajim architecture.
> What I used to generate docs is *Epydoc*: http://epydoc.sourceforge.net/
> This is probably the best docs-generator available for Python.
> Config file used to create docs linked above is here:
> http://kernel.agh.edu.pl/~vardo/gajim/epydoc.conf
> Generally, to generate api docs, in main Gajim's directory, execute:
> # epydoc --conf=epydoc.conf
> And, that's it. Docs will be in 'apidocs/' directory.
> If we decide to document code more, we'll have to choose from three
> possible markups:
> * epytext: http://epydoc.sourceforge.net/epytextintro.html
> * reStructuredText: http://epydoc.sourceforge.net/manual-othermarkup.html
> * Javadoc: http://epydoc.sourceforge.net/manual-othermarkup.html
> (bottom of page)
> Available fields described here: http://epydoc.sourceforge.net/fields.html
> Generally, I would opt for epytext (this is default markup) as this is
> probably the best implemented one in Epydoc and very similar to
> Javadoc, which is probably known to most of us. Or we could use
> Javadoc itself. This way, we will be able to use other doc-generators,
> like Doxygen.
> Of course there's also pydoc, which we might also consider, if it
> suits our needs (it's not very sophisticated):
> http://docs.python.org/lib/module-pydoc
> Here's a comparison of doc-generators:
> http://en.wikipedia.org/wiki/Comparison_of_documentation_generators
> Maybe someone will spot something potentially useful.
> Summarizing, the questions is: how should I document my code? :)
> Thanks for answers in advance.

More information about the Gajim-devel mailing list