Re: [ESPResSo-devel] Developer's documentation format

[Christoph Junghans]

Am 03/14/2011 11:45 AM, schrieb Olaf Lenz:
> Hi everybody!
>
> Besides the pure source code docs of ESPResSo, there are a number of
> other documentation pieces for ESPResSo that partly exist and partly
> should be written:
>    * How to use git for ESPResSo development
>    * Coding conventions for ES
>    * How to add files to ES
>    * Using and modifying the build system
>    * Programmer's Guide ("Under the hood")
>
> However, at the moment I am not sure in what format and where to put
> this kind of documentation. So far, this kind of stuff was supposed to
> go into the "Developer's Guide" which was written in the Doxygen format
> and bundled with the source code documentation. However, I have the
> feeling that it was very hard to access the Developer's Guide and also
> to modify it, as Doxygen has a very strange format for additional
> information.
>
> I can think of a number of options, but I do not know which one to use:
>
> * Using doxygen (as it was so far)
>    * Pro: code documentation and developer's docs together
>    * Con: nasty doxygen format
>    * Con: confusing doxygen docs
>    * Con: hard to edit
>    * Con: not always up-to-date
For API documentation there is basically no way around doxygen, but we 
need a mini-guide for that.
> * In the ESPResSo-wiki on http://espressomd.org
>    * Pro: easy to edit
>    * Pro: always up-to-date
>    * Con: only available when online
>    * Con: yet another account, yet another format
I tend to disagree here, the old espresso wiki was always out of sync 
and outdated. Also the workflow, change something in the code, go to 
wiki and change it there again is quite inconvenient.

> * In an extra LaTeX-PDF-document, or as part of the UG
>    * Pro: comes with source code
>    * Pro: same format as UG
>    * Con: hard to edit
>    * Con: not always up-to-date
>
> * Using GNU Savannah's documentation features ("Cookbook")
>    * https://savannah.nongnu.org/cookbook/?group=espressomd
>    * Pro: location where it would belong to "naturally"
>    * Con: yet another format format
>    * Con: confusing page
>
> Does anyone of you have suggestions which one of these options to
> choose? Or does anyone have another idea?
>
> I believe that I would prefer either the wiki or the LaTeX document, but
> I'm open for other ideas.
For votca we are using txt2tags (t2t) for some parts of the 
documentation. The big advantage is that once you have written something 
in t2t, you can convert it to html, mediawiki or latex. That makes it 
easy to keep documentation in different places/formats in sync. txt2tags 
is just one python script, no other dependencies.
However, yet another format ;-)

Cheers,

Christoph
> Olaf

--
Dr. Christoph Junghans
Max Planck Institute for Polymer Research
Theory Group
POBox 3148
D 55021 Mainz, Germany

Phone: +49 6131 379 335
Web: http://www.mpip-mainz.mpg.de/~junghans