FAQ
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

Search Discussions

  • David Goodger at Mar 7, 2006 at 3:19 am
    [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
  • Nicola Larosa at Mar 7, 2006 at 7:21 am

    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
  • Fredrik Lundh at Mar 7, 2006 at 8:18 am

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
groupdoc-sig @
categoriespython
postedMar 6, '06 at 6:07p
activeMar 7, '06 at 8:18a
posts4
users4
websitepython.org

People

Translate

site design / logo © 2019 Grokbase