[Doc-SIG] docutils, ReST, and pydoc

[David Goodger]

[John M. Gabriele]
> Holy mackerel! I just read a good portion of PEP 287
> http://www.python.org/peps/pep-0287.html and it seems
> clear to me that I should be able to put reStructured
> text right into my docstrings and then read them nicely
> rendered with the pydoc command.

(note: it's spelled "reStructuredText", all one word,
abbreviated reST or ReST or RST, but not REST)

> Is it a foregone conclusion that this functionality
> will soon be built into standard Python?

No.  PEP stands for "Python Enhancement *Proposal*", and PEP 287 is
still "State: Draft".

> What sticking points are we currently facing?

Completion of the necessary features, especially the Docutils PySource
Reader.

> I took a brief look at the docutils page. Is it possible
> that the project has bitten off more than it can chew?

It's an ambitious project, certainly.  What's the point if it's not a
challenge? (0.5 ;-)  Many lesser attempts have fallen by the wayside.
Docutils has had a lot of success so far.

> That is, it looks like they're building a very general tool,
> whereas Python may simply need to have pydoc properly render
> ReST in docstrings so I can run "pydoc some_module" and
> get some nice manpage-style (perldoc style) documentation
> right there in my terminal.

Such tools already exist, such as Epydoc, Pudge, and Endo.  Simply
rendering reST is easy.  Adding hyperlinks and the correct context is
the challenge.  Doing it without importing the code you're documenting
is important too.

Read PEP 258, especially the "Python Source Reader" section for more
on the vision behind the tool *I* want, and that I'll build
(eventually) if no one beats me to it.  (Note: I haven't taken a good
look at Pudge or Endo yet; they may have already done the hard
lifting.)

-- 
David Goodger <http://python.net/~goodger>

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 249 bytes
Desc: OpenPGP digital signature
Url : http://mail.python.org/pipermail/doc-sig/attachments/20060306/de53cb45/attachment.pgp