docutils, ReST, and pydoc

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

docutils, ReST, and pydoc

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.

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

If so, how long until that happens? What sticking points
are we currently facing?

I took a brief look at the docutils page. Is it possible
that the project has bitten off more than it can chew? 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.

Thanks,
---John


__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around
http://mail.yahoo.com 
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: 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>


_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig

signature.asc (257 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: docutils, ReST, and pydoc

Nicola Larosa
>> 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.

For reference:

Epydoc
http://epydoc.sourceforge.net/

Pudge
http://pudge.lesscode.org/

Endo (part of the Enthought Tool Suite)
http://code.enthought.com/ets/

Did not know about this, thanks David.

There's also docextractor:

http://codespeak.net/svn/user/mwh/docextractor/trunk/

API docs
http://radeex.blogspot.com/2006/02/api-docs.html

--
Nicola Larosa - http://www.tekNico.net/

It will always be true that people that drive slower than me are morons,
and people that drive faster than me are idiots. :)
 -- Matthew Carlisle on Slashdot, December 2005

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: docutils, ReST, and pydoc

Fredrik Lundh
Nicola Larosa wrote:

> There's also docextractor:
>
> http://codespeak.net/svn/user/mwh/docextractor/trunk/

and pythondoc:

    http://www.effbot.org/zone/pythondoc.htm

</F>



_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig