[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>
signature.asc
Description: OpenPGP digital signature
_______________________________________________ Doc-SIG maillist - Doc-SIG@python.org http://mail.python.org/mailman/listinfo/doc-sig
