FAQ
I've been documenting UpLib with a combo of ReST for the standalone
docs, and epydoc for the API documentation. But epydoc seems to be
dying a slow death of non-maintenance. It won't work with docutils 0.6
or 0.7, and Python 2.6 seems to crash when running it.

So, I'm looking for an alternative to epydoc. Preferably something
easy to convert to... Any pointers?

Bill

Search Discussions

  • Laura Creighton at Oct 6, 2010 at 7:02 pm

    In a message of Wed, 06 Oct 2010 09:52:15 PDT, Bill Janssen writes:
    I've been documenting UpLib with a combo of ReST for the standalone
    docs, and epydoc for the API documentation. But epydoc seems to be
    dying a slow death of non-maintenance. It won't work with docutils 0.6
    or 0.7, and Python 2.6 seems to crash when running it.

    So, I'm looking for an alternative to epydoc. Preferably something
    easy to convert to... Any pointers?

    Bill
    I've been using endo, which is part of the enthought tools suite.

    https://svn.enthought.com/enthought/wiki/EndoHowTo

    Laura
  • Robert Kern at Oct 6, 2010 at 11:00 pm

    On 10/6/10 2:02 PM, Laura Creighton wrote:
    In a message of Wed, 06 Oct 2010 09:52:15 PDT, Bill Janssen writes:
    I've been documenting UpLib with a combo of ReST for the standalone
    docs, and epydoc for the API documentation. But epydoc seems to be
    dying a slow death of non-maintenance. It won't work with docutils 0.6
    or 0.7, and Python 2.6 seems to crash when running it.

    So, I'm looking for an alternative to epydoc. Preferably something
    easy to convert to... Any pointers?

    Bill
    I've been using endo, which is part of the enthought tools suite.

    https://svn.enthought.com/enthought/wiki/EndoHowTo
    endo is even more non-maintained. I'm honestly surprised it's working for you.

    --
    Robert Kern

    "I have come to believe that the whole world is an enigma, a harmless enigma
    that is made terrible by our own mad attempt to interpret it as though it had
    an underlying truth."
    -- Umberto Eco
  • INADA Naoki at Oct 7, 2010 at 12:08 pm
    bzr [#1] uses pydoctor [#2] for api reference [#3].

    [#1] http://bazaar.canonical.com/
    [#2] http://codespeak.net/~mwh/pydoctor/
    [#3] http://people.canonical.com/~mwh/bzrlibapi/
    On Thu, Oct 7, 2010 at 1:52 AM, Bill Janssen wrote:
    I've been documenting UpLib with a combo of ReST for the standalone
    docs, and epydoc for the API documentation. ?But epydoc seems to be
    dying a slow death of non-maintenance. ?It won't work with docutils 0.6
    or 0.7, and Python 2.6 seems to crash when running it.

    So, I'm looking for an alternative to epydoc. ?Preferably something
    easy to convert to... ?Any pointers?

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


    --
    INADA Naoki? <songofacandy at gmail.com>
  • Michael Foord at Oct 7, 2010 at 12:12 pm

    On 07/10/2010 13:08, INADA Naoki wrote:
    bzr [#1] uses pydoctor [#2] for api reference [#3].

    [#1] http://bazaar.canonical.com/
    [#2] http://codespeak.net/~mwh/pydoctor/
    [#3] http://people.canonical.com/~mwh/bzrlibapi/
    These days all the cool kids* are using Sphinx and the autodoc extension:

    http://sphinx.pocoo.org/ext/autodoc.html

    All the best,

    Michael

    * I'm not one of the cool kids unfortunately... I still tend to think
    that documentation and docstrings are two different things.
    On Thu, Oct 7, 2010 at 1:52 AM, Bill Janssenwrote:
    I've been documenting UpLib with a combo of ReST for the standalone
    docs, and epydoc for the API documentation. But epydoc seems to be
    dying a slow death of non-maintenance. It won't work with docutils 0.6
    or 0.7, and Python 2.6 seems to crash when running it.

    So, I'm looking for an alternative to epydoc. Preferably something
    easy to convert to... Any pointers?

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

    --

    http://www.voidspace.org.uk/

    READ CAREFULLY. By accepting and reading this email you agree,
    on behalf of your employer, to release me from all obligations
    and waivers arising from any and all NON-NEGOTIATED agreements,
    licenses, terms-of-service, shrinkwrap, clickwrap, browsewrap,
    confidentiality, non-disclosure, non-compete and acceptable use
    policies (?BOGUS AGREEMENTS?) that I have entered into with your
    employer, its partners, licensors, agents and assigns, in
    perpetuity, without prejudice to my ongoing rights and privileges.
    You further represent that you have the authority to release me
    from any BOGUS AGREEMENTS on behalf of your employer.
  • Michael Foord at Oct 7, 2010 at 12:19 pm

    On 07/10/2010 13:12, Michael Foord wrote:
    On 07/10/2010 13:08, INADA Naoki wrote:
    bzr [#1] uses pydoctor [#2] for api reference [#3].

    [#1] http://bazaar.canonical.com/
    [#2] http://codespeak.net/~mwh/pydoctor/
    [#3] http://people.canonical.com/~mwh/bzrlibapi/
    These days all the cool kids* are using Sphinx and the autodoc extension:

    http://sphinx.pocoo.org/ext/autodoc.html
    Ooh, along with the autosummary extension:

    http://sphinx.pocoo.org/ext/autosummary.html

    (This generates the templates used by autodoc if I am understanding
    correctly - so autodoc pulls in explicitly specified docstrings and
    autosummary generates stub pages that pull in all docstrings.)

    The autosummary doc starts:

    "This extension generates function/method/attribute summary lists,
    similar to those output e.g. by Epydoc and other API doc generation tools."

    All the best,


    Michael
    All the best,

    Michael

    * I'm not one of the cool kids unfortunately... I still tend to think
    that documentation and docstrings are two different things.
    On Thu, Oct 7, 2010 at 1:52 AM, Bill Janssenwrote:
    I've been documenting UpLib with a combo of ReST for the standalone
    docs, and epydoc for the API documentation. But epydoc seems to be
    dying a slow death of non-maintenance. It won't work with docutils 0.6
    or 0.7, and Python 2.6 seems to crash when running it.

    So, I'm looking for an alternative to epydoc. Preferably something
    easy to convert to... Any pointers?

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

    --

    http://www.voidspace.org.uk/

    READ CAREFULLY. By accepting and reading this email you agree,
    on behalf of your employer, to release me from all obligations
    and waivers arising from any and all NON-NEGOTIATED agreements,
    licenses, terms-of-service, shrinkwrap, clickwrap, browsewrap,
    confidentiality, non-disclosure, non-compete and acceptable use
    policies (?BOGUS AGREEMENTS?) that I have entered into with your
    employer, its partners, licensors, agents and assigns, in
    perpetuity, without prejudice to my ongoing rights and privileges.
    You further represent that you have the authority to release me
    from any BOGUS AGREEMENTS on behalf of your employer.
  • Fred Drake at Oct 7, 2010 at 12:21 pm

    On Thu, Oct 7, 2010 at 8:12 AM, Michael Foord wrote:
    * I'm not one of the cool kids unfortunately... I still tend to think that
    documentation and docstrings are two different things.
    Not so unfortunate. The usage patterns are very different, so the
    appropriate content is as well.


    ? -Fred

    --
    Fred L. Drake, Jr.? ? <fdrake at acm.org>
    "A storm broke loose in my mind."? --Albert Einstein
  • Bill Janssen at Oct 7, 2010 at 4:07 pm
    Thanks. There's a nice list at
    http://wiki.python.org/moin/DocumentationTools (autodoc isn't mentioned).

    Personally, I think I'm going to try Doxygen first. There's lots of
    non-Python code in UpLib, too.

    Bill

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
groupdoc-sig @
categoriespython
postedOct 6, '10 at 4:52p
activeOct 7, '10 at 4:07p
posts8
users6
websitepython.org

People

Translate

site design / logo © 2019 Grokbase