Hey, 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, steve-e [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. > _______________________________________________ Gajim-devel mailing list Gajim-devel@gajim.org https://lists.gajim.org/cgi-bin/listinfo/gajim-devel
