Re: [pygccxml-development] Updated status

[Matthias B. <ba...@ir...>]

Allen Bierbaum wrote:
> Toward this goal (and following up on Matthias's comments from last 
> week), I started looking at what it would take to generate documentation 
> using epydoc and restructuredtext.  I added a script in 
> "experimental/docs/generate_all_docs.py" that will call epydoc with what 
> I think are the correct parameters to generate html documentation.  I 
> also started converting pypp_api over to use restructured text for 
> documentation. The only problem is that it looks like the tags/fields I 
> am using are not being recognized correctly (ex: params, args, etc).  
> According to the docs I am doing things correctly but it is just not 
> working.  If either of you have experience with this tool please take a 
> look and let me know if I am doing something wrong.

We're using epydoc for the PyODE manual, but we're actually using it 
with epytext markup, not rest. But anyway, I'm no expert with epydoc, 
I'm more used to doxygen.

The "experimental" directory is no package, so I had to change the 
"experimental" entry in generate_all_docs.py to "experimental/pypp_api.py".
epydoc actually generates errors on pypp_api.py. Your doc strings 
usually begin with blanks, obviously epydoc things the text is indented 
and generates errors. To test epydoc I changed the doc string for 
ModuleBuilder.__init__ as follows:

       """Initialize module.

          :Parameters:
             - `workingDir`: Directory to start processing.  (default: 
current working dir)
             - `includePaths`: List of paths to tell gccxml to search 
for header files.
             - `gccxmlPath`:   path to gccxml.  If not set then attempt 
to find it in system path.
             - `defines`:  set of symbols to add as defined when compiling.
             - `undefines`:  set of symbols to add as undefined when 
compiling.
             - `cacheFile`:    name of file to use for caching parse 
data for this module.
             - `verbose`:      if true output status and command 
information as building the module.
       """

That is, I moved the first line to the beginning of the string, I 
changed the apostrophes of the list entries into those "backticks" (or 
what are they called?) and I split the docs for define/undefine into two 
entries.
With those changes, epydoc seems to recognize the stuff but the result 
looks somewhat weird. On the generated page each line describing an 
argument begins on a new line (i.e. the argument name and its 
documentation are on two *separate* lines). This looks particularly 
weird, when I also add the type information. This rather looks like a 
bug to me.
I also tested with epytext markup and then the results look normal. So 
maybe we should consider switching to that markup...?

> Does this seem like a good direction for documentation?  I know we can 
> document classes and methods using this, do we want to document the 
> usage of the modules like this as well?  (it is supported but do we want 
> that type of documentation in the code?)

Well, I guess a short usage information in the module or class doc 
string doesn't do any harm. But I guess as there is a dedicated "docs" 
directory already existing in pyplusplus this would probably be a better 
place for adding any tutorial/introduction style thing. But I leave that 
up to Roman how he wants the documentation to be organized.


- Matthias -