paparazzi-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Paparazzi-devel] Re: Improving documentation


From: Chris Gough
Subject: Re: [Paparazzi-devel] Re: Improving documentation
Date: Wed, 21 Jul 2010 16:11:00 +1000

On Wed, Jul 21, 2010 at 2:46 PM, Serge Le Huitouze
<address@hidden> wrote:
> Ideally, a litProg/documentation system should be able to handle all
> the languages used in the project (this probably includes makefiles...),
> but I'm not sure such a beast exists, and, in case it does, I'm not sure it'd
> be practical...

I think there are two approaches:
 * parse/generate "documented code stubs" all in the same language,
then generate docs from them.
 * generate documents with native tools, then combine them with
another documentation layer.

These examples [1], [2] demonstrate the first approach. They uses
Doxygen, but only after running a program that generates documented
C++ stubs from python sources. I'd be surprised if an OCaml equivalent
already exists, but OCamldoc custom generators [3] make it seem quite
plausible.

 [1] http://i31www.ira.uka.de/~baas/pydoxy/
 [2] http://code.foosel.org/doxypy
 [3] http://caml.inria.fr/pub/docs/manual-ocaml/manual029.html#toc112

This [4] demonstrates the second approach. It shows ReStructuredText
integrating native python document generation (with spinx) with
Doxygen-generated content in a loosely coupled way. Trivial to extend
it to include OCamldoc generated documents (custom generator not
required). WikiMarkup could be substituted for ReStructuredText here,
but it would required a streamlined way of publishing built-out docs.

 [4] 
http://stackoverflow.com/questions/835043/has-anyone-used-sphinx-to-document-a-c-project

Chris Gough



reply via email to

[Prev in Thread] Current Thread [Next in Thread]