[Numpy-discussion] Documentation using PyDoc

[Todd Miller]

On Wed, 2003-10-22 at 19:19, Colin J. Williams wrote:
> [Message copied to comp.lang.python]
> 
> I am building a module which is based on the numarray package and its 
> sub-packages.
> 
> I am proposing to use PyDoc to document this module.  The problem is 
> that PyDoc generates links to documentation on the imported modules and 
> expects to find HTML files in the style: nameOfImportedModule.html.
> 
I'm not sure I fully understand the problem,  but I just tried:

>>> import pydoc
>>> pydoc.writedoc("numarray.generic")

This produced numarray.generic.html.

> The numarray documentation is not in this style.

The manual certainly isn't,  but is Python's own manual in this style?
 
> Is there some way that I can guide PyDoc in the generation of names to 
> the imported links?

See above.

> Supposing I create my own links, how can I ensure that these 
> automatically call the appropriate node in the numarray tree?
> 
> Is there any possibility that the numarray documentation could be 
> generated by PyDoc?

Yes and no.  Numarray already has doc-strings which probably need more
work. The numarray manual is not going to suddenly transform into pydoc
format.
 
> I would appreciate any advice.

That's my $.02

> Colin W.
> 
> PS I don't see any documentation on the generic module.
> 
What information exists is recorded in a combination of the manual, the
generic.py doc-strings, and Doc/design.txt.  design.txt looks like it
has some bit-rot (especially the C-API).

There's probably not as much info as you want,  but I think what you're
trying to do (create an NDArray or NumArray subclass) is at the
forefront of numarray development so you may to have to read code or ask
specific questions to find out what you want to know.

Regards, 
Todd
-- 
Todd Miller 			
Space Telescope Science Institute
3700 San Martin Drive
Baltimore MD, 21030
(410) 338 - 4576