Re: [pygccxml-development] Updated status

[Allen B. <al...@vr...>]

Matthias Baas wrote:

> 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".

My bad.  I forgot to check in the __init__.py file I was using. :(

> 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...?

I am fine with using epytext (or even javadoc).  I was trying to use 
rest since Roman already used it, but I agree that it looks like there 
are still some bugs processing it.  I am more interested in getting good 
documentation in place then I am in working around bugs and picky parsers.

>
>> 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.

Agreed.  I will go in whatever direction you both think is best.

-Allen