Re: [pygccxml-development] Updated status
Brought to you by:
mbaas,
roman_yakovenko
From: Matthias B. <ba...@ir...> - 2006-03-06 19:00:44
|
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 - |