Re: [Docutils-users] Programming reference documentation

[Ian B. <ia...@co...>]

On Sat, 2003-01-18 at 10:34, David Goodger wrote:
> > I'm working with the Webware project (webware.sf.net), and we really
> > need some cohesive reference documentation, aimed particularly at
> > the public interfaces.  I'm wondering if anyone is using docutils
> > for this now... if so, I'd like to see how it's working.  It's not
> > entirely clear to me what docutils status is (I've used reST a lot,
> > but not much else).
> 
> Are you referring to "auto-documentation" (extracting documentation
> from source code)?  I have begun work on a Python Source Reader
> component which will accomplish this.  The code so far is in
> docutils/readers/python/moduleparser.py.  The plan is described in PEP
> 258 (<http://docutils.sf.net/spec/pep-0258.html>),
> <http://docutils.sf.net/spec/pysource.html>, and
> <http://docutils.sf.net/spec/notes.html#python-source-reader>.

Yes, I'm thinking of auto-documentation, or at least documentation with
an automated step.

> The Python Reader package doesn't extract docstrings yet.  I'm
> currently concentrating on finding a new job [#]_, which means I don't
> know how much time I'll be able to devote to this.
> 
> .. [#] Check out my resume at
>    <http://starship.python.net/~dgoodger/cv/>!  Please tell your
>    friends, relatives, neighbors, managers, and HR people!  Let me
>    know if you have any leads.  Thanks!

You're in Canada, right?  My scant connections don't go as far as
Canada, but who knows...

> > * Using internal references in those docstrings, so I could
> >   effectively include the docstrings from other portions of code
> >   (classes, methods, etc).
> 
> I hadn't thought of that approach.  From your description, it seems to
> require a lot of bookkeeping and redundancy, which I wouldn't want to
> write or require others to write.  But I encourage you to explore it.

It's about the same amount of bookkeeping that you'd need to create a
high-quality reference document (like the Python module documentation,
for instance).  It should be about as difficult to write.  The advantage
would be entirely in the maintenance, by having code and documentation
next to each other.

Some of the bookkeeping might be possible to ease -- for instance,
keeping track of methods that aren't included and giving a warning (so
you don't forget to include documentation you wrote).  Or maybe have a
directive that would just include all the documentation of the class or
module -- either ordered like in the source, or ordered alphabetically. 

> > One thing I *don't* like is reference documentation in the style of
> > pydoc.  To me it's too automatic, and generally too hard to follow.
> 
> I hope that Docutils' auto-documentation will be more flexible than
> pydoc's, although it will have the same basis.  It will certainly have
> more flexible rendering, and I hope much more readable.
> 
> > I find reference documentation with some framework of text (lead-in
> > paragraphs, categorization, etc) to be much better.
> 
> That can be tricky.  One idea I had (documented in the spec/notes
> file) is to recognize JavaDoc-style documentation comments almost
> anywhere in the code.  This would allow a more "literate programming"
> approach than what pydoc provides.

If everything is ordered like in the source, perhaps a comment (or plain
string) could be parsed out as in-between text.  Like:

"""
These functions are all dangerous:
"""

def yadayada():
    "docs for this"

And so on... they could appear in class definitions as well.  That they
are strings implies they are different than mere comments -- most of the
comments I write are intended to be read by someone reading the code,
and I have no desire to separate them into documentation; I'd be willing
to make that distinction strict in the code I work with.

But that's harder to work with than inclusion, because your narrative is
split up all over the place with lots of code in between.  

> > There are also
> > methods which, while "public" aren't actually useful, and I don't
> > think those should be documented -- they are just distracting.
> 
> How could software tell the difference?  If we can come up with an
> unobtrusive way to tell the docstring processing system to disregard
> certain methods, it could be useful.  Maybe a class attribute
> equivalent of the "__all__" module attribute?  Or perhaps the
> opposite: a "__none__" class attribute ;).

Well, there could be a directive in the docstring like:

  .. public: no

Or I guess it would be more appropriate:

  :Public: no

"Public" probably isn't the right term, but something like that. 
":Obscure: yes" might be more correct ;)

-- 
Ian Bicking           Colorstudy Web Development
ia...@co...   http://www.colorstudy.com
PGP: gpg --keyserver pgp.mit.edu --recv-keys 0x9B9E28B7
4869 N Talman Ave, Chicago, IL 60625 / (773) 275-7241