From janssen at parc.com  Wed Oct  6 18:52:15 2010
From: janssen at parc.com (Bill Janssen)
Date: Wed, 6 Oct 2010 09:52:15 PDT
Subject: [Doc-SIG] alternatives to epydoc?
Message-ID: <38453.1286383935@parc.com>

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

From lac at openend.se  Wed Oct  6 21:02:28 2010
From: lac at openend.se (Laura Creighton)
Date: Wed, 06 Oct 2010 21:02:28 +0200
Subject: [Doc-SIG] alternatives to epydoc?
In-Reply-To: Message from Bill Janssen <janssen@parc.com> 
	of "Wed, 06 Oct 2010 09:52:15 PDT." <38453.1286383935@parc.com> 
References: <38453.1286383935@parc.com> 
Message-ID: <201010061902.o96J2SJ5019422@theraft.openend.se>

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 


From robert.kern at gmail.com  Thu Oct  7 01:00:45 2010
From: robert.kern at gmail.com (Robert Kern)
Date: Wed, 06 Oct 2010 18:00:45 -0500
Subject: [Doc-SIG] alternatives to epydoc?
In-Reply-To: <201010061902.o96J2SJ5019422@theraft.openend.se>
References: <38453.1286383935@parc.com>
	<201010061902.o96J2SJ5019422@theraft.openend.se>
Message-ID: <i8iv2t$t7j$1@dough.gmane.org>

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


From songofacandy at gmail.com  Thu Oct  7 14:08:48 2010
From: songofacandy at gmail.com (INADA Naoki)
Date: Thu, 7 Oct 2010 21:08:48 +0900
Subject: [Doc-SIG] alternatives to epydoc?
In-Reply-To: <38453.1286383935@parc.com>
References: <38453.1286383935@parc.com>
Message-ID: <AANLkTinDmpzr0vSUono-2rhGQMVjxr246cFKM=7Zey8F@mail.gmail.com>

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 at 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 at python.org
> http://mail.python.org/mailman/listinfo/doc-sig
>



-- 
INADA Naoki? <songofacandy at gmail.com>

From fuzzyman at voidspace.org.uk  Thu Oct  7 14:12:12 2010
From: fuzzyman at voidspace.org.uk (Michael Foord)
Date: Thu, 07 Oct 2010 13:12:12 +0100
Subject: [Doc-SIG] alternatives to epydoc?
In-Reply-To: <AANLkTinDmpzr0vSUono-2rhGQMVjxr246cFKM=7Zey8F@mail.gmail.com>
References: <38453.1286383935@parc.com>
	<AANLkTinDmpzr0vSUono-2rhGQMVjxr246cFKM=7Zey8F@mail.gmail.com>
Message-ID: <4CADB91C.5070309@voidspace.org.uk>

  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 at 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 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.


From fuzzyman at voidspace.org.uk  Thu Oct  7 14:19:12 2010
From: fuzzyman at voidspace.org.uk (Michael Foord)
Date: Thu, 07 Oct 2010 13:19:12 +0100
Subject: [Doc-SIG] alternatives to epydoc?
In-Reply-To: <4CADB91C.5070309@voidspace.org.uk>
References: <38453.1286383935@parc.com>	<AANLkTinDmpzr0vSUono-2rhGQMVjxr246cFKM=7Zey8F@mail.gmail.com>
	<4CADB91C.5070309@voidspace.org.uk>
Message-ID: <4CADBAC0.3020703@voidspace.org.uk>

  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 Janssen<janssen at 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 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.


From fdrake at acm.org  Thu Oct  7 14:21:19 2010
From: fdrake at acm.org (Fred Drake)
Date: Thu, 7 Oct 2010 08:21:19 -0400
Subject: [Doc-SIG] alternatives to epydoc?
In-Reply-To: <4CADB91C.5070309@voidspace.org.uk>
References: <38453.1286383935@parc.com>
	<AANLkTinDmpzr0vSUono-2rhGQMVjxr246cFKM=7Zey8F@mail.gmail.com>
	<4CADB91C.5070309@voidspace.org.uk>
Message-ID: <AANLkTikAn7D51SK8gKVVwNMJL6JUDp4wDBv70rH+HBES@mail.gmail.com>

On Thu, Oct 7, 2010 at 8:12 AM, Michael Foord <fuzzyman at 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

From janssen at parc.com  Thu Oct  7 18:07:38 2010
From: janssen at parc.com (Bill Janssen)
Date: Thu, 7 Oct 2010 09:07:38 PDT
Subject: [Doc-SIG] alternatives to epydoc?
In-Reply-To: <4CADB91C.5070309@voidspace.org.uk>
References: <38453.1286383935@parc.com>
	<AANLkTinDmpzr0vSUono-2rhGQMVjxr246cFKM=7Zey8F@mail.gmail.com>
	<4CADB91C.5070309@voidspace.org.uk>
Message-ID: <33131.1286467658@parc.com>

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