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
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 <janssen@parc.com> 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@python.org http://mail.python.org/mailman/listinfo/doc-sig
-- INADA Naoki <songofacandy@gmail.com>
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 Janssen<janssen@parc.com> 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@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.
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:
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 Janssen<janssen@parc.com> 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@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.
On Thu, Oct 7, 2010 at 8:12 AM, Michael Foord <fuzzyman@voidspace.org.uk> 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
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
participants (4)
-
Bill Janssen -
Fred Drake -
INADA Naoki -
Michael Foord