[Doc-SIG] PyDoc discussion

[Ron Adam]

David Goodger wrote:
> On 4/12/07, Ron Adam <rrr at ronadam.com> wrote:
>> Would anyone here be interested in discussing details of the pydoc 
>> rewrite
>> I've been working on?
> 
> Yes, I would like to hear about it, and I think others would too.
> 
>> And is this a good place for that?
> 
> As good a place as any, I'd say ;-)
> You may want to let python-dev & python-list know that a discussion is
> happening here.

After looking at docutils a bit further, I've decided to include a 
formatter to output ReST-text so that the output from pydoc can be used 
with distutils.

If a docstring is already in Rest, it will just pass it though, the output 
of the pydoc sections, lists and items will be formatted in ReST to match.

Then docutils can be used to translate it to other formats.


I'll also try make a formatter that will output a distutils data structure. 
  That will be a bit more difficult but should be doable.  I think the data 
structure I'm using isn't all that different.

In this case pydoc will need to use docutils to parse the doc string.  The 
rest of the documents can be mapped directly to the docutils data structure.


I also want to be able to request (from pydoc) individual parts in a way 
that they can be formatted and then assembled later or included in other 
documents easily.

I'd be interested in hearing any thoughts on these ideas.

Cheers,
    Ron