docutils-develop

RE: [Docutils-develop] docutils api docs

[Tony J I. (Tibs) <to...@ls...>]

Richard Jones wrote:
> I lieu of a "usable" version of the docutils python API doc
> extractor, I've run epydoc over the docutils tree, producing:
>
>   http://docutils.sourceforge.net/apidoc/docutils.html

Ooh - that's seriously pretty looking stuff!

(whether it's *useful* I'll leave to others, since I've not time to look
it over, but it is *does* look nice)

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
A single element tuple needs a trailing comma, and an empty tuple needs
brackets to distinguish it from a coffee stain. - Duncan Booth, in his
intro to Python for the ACCU Spring 2002 conference
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

RE: [Docutils-develop] docutils api docs

[Tony J I. (Tibs) <to...@ls...>]

David Goodger wrote:
> I recently moved the bibliographic fields that were in all the
> module docstrings into simple comments.  This gets rid of ":Author:
> David Goodger :Contact: goodger@users." from the API docs of almost
> EVERY SINGLE MODULE ENTRY!

I'd wondered why you'd done that - it seems like docstring-relevant
stuff to me. Is it just embarassment over having your name everywhere? I
mean, if you wrote it...

Tibs
--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

Re: [Docutils-develop] docutils api docs

[David G. <go...@us...>]

> David Goodger wrote:
>> I recently moved the bibliographic fields that were in all the
>> module docstrings into simple comments.  This gets rid of ":Author:
>> David Goodger :Contact: goodger@users." from the API docs of almost
>> EVERY SINGLE MODULE ENTRY!

Tony J Ibbs (Tibs) wrote:
> I'd wondered why you'd done that - it seems like docstring-relevant
> stuff to me. Is it just embarassment over having your name everywhere? I
> mean, if you wrote it...

It wasn't in anticipation of Richard producing API docs -- those were an
unexpected surprise.  It was in anticipation of eventually producing API
docs; it seemed overly verbose to include that info in every module's
docstring.  The epydoc API docs merely confirmed what I had suspected.  I
began moving them in modules I was editing for some other reason, and then
one day I did a mass edit, made easy thanks to Emacs' directory-edit-mode
and query-replace tools.

Yes, I wrote much of the code, but a comment is good enough.  The developer
looking for API clues doesn't need to see my name front & center.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Re: [Docutils-develop] docutils api docs

[Richard J. <rj...@ek...>]

On Fri, 11 Oct 2002 7:06 pm, Tony J Ibbs (Tibs) wrote:
> Richard Jones wrote:
> > I lieu of a "usable" version of the docutils python API doc
> > extractor, I've run epydoc over the docutils tree, producing:
> >
> >   http://docutils.sourceforge.net/apidoc/docutils.html
>
> Ooh - that's seriously pretty looking stuff!
>
> (whether it's *useful* I'll leave to others, since I've not time to look
> it over, but it is *does* look nice)

It has some really good ideas in the output (the structure of the pages, and 
the class heirarchies) that'd be nice to mimic in the docutils output - which 
at the moment is One Big Page :)

I haven't had a chance to look into what it takes to play with the current 
docutils pysource effort to produce a similar output.


   Richard

Re: [Docutils-develop] docutils api docs

[David G. <go...@us...>]

Richard Jones wrote:
> It has some really good ideas in the output

Agreed.

> I haven't had a chance to look into what it takes to play with the
> current docutils pysource effort to produce a similar output.

Unless you've made some radical changes to the sandbox/tibs/pysource
code (I confess that I haven't looked it over thoroughly), it still
takes a very different path to create its output.  You (and anybody
interested) should read these first:

* http://docutils.sf.net/spec/pysource.html
* http://docutils.sf.net/spec/pep-0258.html#python-source-reader
* http://docutils.sf.net/sandbox/tibs/pysource/notes/thoughts.html

The last one consists of Tibs' parting notes summing up his ideas
about where to go from here, and is especially relevant.  I see you
caught it from docutils-checkins though.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/