FAQ
I notice that the Python documentation is written in reStructuredText,
but that docutils is not part of the Python standard library. Is there
any reason why docutils doesn't come stock with Python? Is it missing
critical features? What's holding it back?

For comparison, when you install Perl, the basic tools for reading POD
(and converting it to other formats) come standard. And this is
*Perl*, where there's supposed to be more than one way to do it and
they very rarely impose any standard way to do anything upon the user.

Quick observation to mention: I can't remember the last time I looked
at the docs for a Python distribution and they weren't formatted in
reStructuredText.

Search Discussions

  • Jeff Rush at Jan 2, 2009 at 3:15 am

    ex cord wrote:
    I notice that the Python documentation is written in reStructuredText,
    but that docutils is not part of the Python standard library. Is there
    any reason why docutils doesn't come stock with Python? Is it missing
    critical features? What's holding it back?
    There is a document outlining what needs to be improved in docutils before it
    is ready for inclusion in the standard library:

    http://docutils.sourceforge.net/docs/dev/todo.html#minimum-requirements-for-python-standard-library-candidacy

    or if that URL causes you trouble, the same page using tinyurl:

    http://tinyurl.com/862f3e

    For comparison, when you install Perl, the basic tools for reading POD
    (and converting it to other formats) come standard. And this is
    *Perl*, where there's supposed to be more than one way to do it and
    they very rarely impose any standard way to do anything upon the user.

    Quick observation to mention: I can't remember the last time I looked
    at the docs for a Python distribution and they weren't formatted in
    reStructuredText.
    Also remember that some projects do not want to be included in the standard
    library because they have different release cycles and bug trackers.

    That said, I look forward to the day it is included as it has become a key
    part of so much I do these days. There are parts of docutils showing their
    age that need work, support for eggs-based plugins that has caused several
    public problems re pathing conflicts, folding in the excellent work done in
    the Sphinx framework for marking up Python, which needs to be added to the
    wiki page:

    http://docutils.sf.net/sandbox/README.html#documenting-python

    It seems the set of developers is too small. Certainly with David Goodger (a
    major force behind docutils) acting as chair of PyCon last year and this
    year, and taking on as of Dec 2008 a full-time position with the PSF, there is
    a need for additional developers to come forward and get excited about the
    possibilities.

    -Jeff
  • Ex cord at Jan 2, 2009 at 4:25 am

    On Thu, Jan 1, 2009 at 10:15 PM, Jeff Rush wrote:
    ex cord wrote:
    I notice that the Python documentation is written in reStructuredText,
    but that docutils is not part of the Python standard library. Is there
    any reason why docutils doesn't come stock with Python? Is it missing
    critical features? What's holding it back?
    There is a document outlining what needs to be improved in docutils before it
    is ready for inclusion in the standard library:

    http://docutils.sourceforge.net/docs/dev/todo.html#minimum-requirements-for-python-standard-library-candidacy

    or if that URL causes you trouble, the same page using tinyurl:

    http://tinyurl.com/862f3e
    Ah. Thanks for the link. It's interesting; a number of those things on
    the list seem pretty fancy. Well, they just seem pretty fancy to me --
    especially if it's regarding using docutils/reST for (A) use in
    docstrings, and (B) use in readme files and other dedicated docs. All
    I'd care about for documenting modules is: can it do italics? bold?
    chapters/sections/subsections? lists? tables? include images? Yeah?
    Great -- use it. Including it with Python's std lib would get even
    more devs using that markup, and there would be more motivation to add
    any extra features to docutils down the road.

    I don't know if Perl's POD has the features on that list. I don't
    think it does. Yet, Perl has volumes of great docs, and almost
    everyone in the Perl community uses that POD markup (which I
    personally never could get used to). In fact, I'm tempted to say that
    Perl has really excellent docs in spite of POD. :)

    Docutils seems to be in this stasis where it's believed that it needs
    more sophisticated features to be included with Python, but users
    would just like some nice markup to use for their docs/docstrings --
    with support for that markup built into Python.
    For comparison, when you install Perl, the basic tools for reading POD
    (and converting it to other formats) come standard. And this is
    *Perl*, where there's supposed to be more than one way to do it and
    they very rarely impose any standard way to do anything upon the user.

    Quick observation to mention: I can't remember the last time I looked
    at the docs for a Python distribution and they weren't formatted in
    reStructuredText.
    Also remember that some projects do not want to be included in the standard
    library because they have different release cycles and bug trackers.
    Do you happen to know if the docutils devs want docutils included with Python?

    Personally, I think it should be the other way around. If all the
    Python devs are using reST everywhere anyway, it would be in their
    best interest for them to just say, "look, we use it, we like it,
    we've actually all become addicted to using it, and everyone else is
    using it too, so let's work out some way to get it in Python for the
    next release, eh?"
    That said, I look forward to the day it is included as it has become a key
    part of so much I do these days. There are parts of docutils showing their
    age that need work, support for eggs-based plugins that has caused several
    public problems re pathing conflicts,
    That's an easy one to solve: don't require docutils to support
    egg-based plug-ins. :) If I want to install a docutils plug-in (I've
    never used one, and didn't even know they existed), then I'll just do
    a ``python setup.py install`` like everyone else. :) Personally, I
    don't care for eggs anyway -- when I install a distribution I want to
    see the source and the docs.
  • Nick Coghlan at Jan 2, 2009 at 5:51 am

    ex cord wrote:
    Personally, I think it should be the other way around. If all the
    Python devs are using reST everywhere anyway, it would be in their
    best interest for them to just say, "look, we use it, we like it,
    we've actually all become addicted to using it, and everyone else is
    using it too, so let's work out some way to get it in Python for the
    next release, eh?"
    Actually, we cheat a bit and drag a copy of docutils into our Docs
    source tree via an external subversion reference:

    ~/devel/python/Doc/tools$ svn info docutils
    Path: docutils
    URL: http://svn.python.org/projects/external/docutils-0.4/docutils
    Repository Root: http://svn.python.org/projects
    Repository UUID: 6015fed2-1504-0410-9fe1-9d1591cc4771
    Revision: 66083
    Node Kind: directory
    Schedule: normal
    Last Changed Author: georg.brandl
    Last Changed Rev: 56857
    Last Changed Date: 2007-08-10 01:52:00 +1000 (Fri, 10 Aug 2007)

    In light of the existence of Sphinx as a higher layer built on top of
    docutils that is appropriate for Python's own documentation, perhaps the
    lower level goals considered appropriate before targeting standard
    library inclusion need to be reconsidered.

    Cheers,
    Nick.

    --
    Nick Coghlan | ncoghlan at gmail.com | Brisbane, Australia
    ---------------------------------------------------------------
  • Jeff Rush at Jan 2, 2009 at 6:32 am

    ex cord wrote:
    On Thu, Jan 1, 2009 at 10:15 PM, Jeff Rush wrote:
    ex cord wrote:
    I notice that the Python documentation is written in reStructuredText,
    but that docutils is not part of the Python standard library. Is there
    any reason why docutils doesn't come stock with Python? Is it missing
    critical features? What's holding it back?
    There is a document outlining what needs to be improved in docutils before it
    is ready for inclusion in the standard library:

    http://docutils.sourceforge.net/docs/dev/todo.html#minimum-requirements-for-python-standard-library-candidacy

    or if that URL causes you trouble, the same page using tinyurl:

    http://tinyurl.com/862f3e
    Ah. Thanks for the link. It's interesting; a number of those things on
    the list seem pretty fancy. Well, they just seem pretty fancy to me --
    especially if it's regarding using docutils/reST for (A) use in
    docstrings, and (B) use in readme files and other dedicated docs. All
    I'd care about for documenting modules is: can it do italics? bold?
    chapters/sections/subsections? lists? tables? include images? Yeah?
    Great -- use it. Including it with Python's std lib would get even
    more devs using that markup, and there would be more motivation to add
    any extra features to docutils down the road.
    Eh, I didn't realize you mean for *docstrings* specifically. There -are-
    competing markup conventions in that arena but not in the README area. The
    PEP about docstring markup itemizes them I believe, and there are those who
    think reST is too heavy-weight for docstrings.

    Also remember that some projects do not want to be included in the standard
    library because they have different release cycles and bug trackers.
    Do you happen to know if the docutils devs want docutils included with Python?
    I don't know but suspect they do, based on that wiki page of what is needed.
    They're just not in a hurry until all the details are right.

    That's an easy one to solve: don't require docutils to support
    egg-based plug-ins. :) If I want to install a docutils plug-in (I've
    never used one, and didn't even know they existed)...
    They don't exist, and that is a problem. I said egg-based plugins because it
    is one of the more popular plugin technologies for Python (the others I'm
    aware of are the Twisted plugins and Zope3 component plugins using utilities).
    So the problem is that people (like me but also many others) want to extend
    docutils with new writers or directives, but lacking a plugin mechanism, end
    up hacking a custom version of docutils. Then people install the hacked
    version for feature X and the standard version for their general environment
    (say via an RPM or egg) and you get tracebacks, because setuptools has one
    rule for ordering eggs (std version) versus non-eggs (custom version), and
    non-setuptools environments has another, and they interfere with each other.
    It's a long story but basically we need a clean way to extend docutils without
    just changing its source, and using the existing eggs plugin mechanism seems a
    quick way to achieve that. Like docutils is a defacto doc standard, eggs are
    a defacto packaging standard for Python, lacking a strong alternative.

    -Jeff
  • Engelbert gruber at Jan 4, 2009 at 1:03 pm

    On Fri, Jan 2, 2009 at 4:15 AM, Jeff Rush wrote:
    ex cord wrote:
    I notice that the Python documentation is written in reStructuredText,
    but that docutils is not part of the Python standard library. Is there
    any reason why docutils doesn't come stock with Python? Is it missing
    critical features? What's holding it back?
    There is a document outlining what needs to be improved in docutils before it
    is ready for inclusion in the standard library:

    http://docutils.sourceforge.net/docs/dev/todo.html#minimum-requirements-for-python-standard-library-candidacy

    or if that URL causes you trouble, the same page using tinyurl:

    http://tinyurl.com/862f3e

    For comparison, when you install Perl, the basic tools for reading POD
    (and converting it to other formats) come standard. And this is
    *Perl*, where there's supposed to be more than one way to do it and
    they very rarely impose any standard way to do anything upon the user.
    as reStructured text is readable without tools, if you look at old README files
    the look similar, so in fact no tool is required. POD has more markup even for
    simple files.

    and of course david has set the bar for inclusion really high.
    Quick observation to mention: I can't remember the last time I looked
    at the docs for a Python distribution and they weren't formatted in
    reStructuredText.
    Also remember that some projects do not want to be included in the standard
    library because they have different release cycles and bug trackers.

    That said, I look forward to the day it is included as it has become a key
    part of so much I do these days. There are parts of docutils showing their
    age that need work, support for eggs-based plugins that has caused several
    public problems re pathing conflicts, folding in the excellent work done in
    the Sphinx framework for marking up Python, which needs to be added to the
    wiki page:

    http://docutils.sf.net/sandbox/README.html#documenting-python

    It seems the set of developers is too small. Certainly with David Goodger (a
    major force behind docutils) acting as chair of PyCon last year and this
    year, and taking on as of Dec 2008 a full-time position with the PSF, there is
    a need for additional developers to come forward and get excited about the
    possibilities.

    -Jeff
    _______________________________________________
    Doc-SIG maillist - Doc-SIG at python.org
    http://mail.python.org/mailman/listinfo/doc-sig

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
groupdoc-sig @
categoriespython
postedJan 1, '09 at 5:21a
activeJan 4, '09 at 1:03p
posts6
users4
websitepython.org

People

Translate

site design / logo © 2019 Grokbase