Re: [Docutils-develop] Re: [Docutils-users] Programming reference documentation

[Beni C. <cb...@te...>]

On 2003-01-20, Ian Bicking wrote:

> On Sun, 2003-01-19 at 06:00, Beni Cherniavsky wrote:
> > Forgot to announce it; since the source reader is not ready for use (is
> > it?),
>
> It seems to work okay for me -- I think David might have some features
> he'd like, but what's there seems sufficient to me.
>
Oops, just now found rjhack.py.  Works great for me.

> >I think somebody might benefit from my solution.  I've written code
> > that was documented with rST docstrings but couldn't use them (pydoc
> > ignores the rST, docutils barfs at the python code).So I took the
> > plain-text formatter of pydoc and hacked it until the result was a
> > document with chapters instead of the "| " nesting, etc., so that it could
> > be processed by the plain rST reader of docutils.
>
> Ack... sounds like a mess.
>
Indeed :).

> > > Ian Bicking wrote:
> > > > 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 find reference documentation with some framework of text (lead-in
> > > > paragraphs, categorization, etc) to be much better.
> > >
> > Like GNU info files tend to be?libc, elisp, make, they have the best
> > hierarchically organised documentation that I've ever read.Puts
> > everything in the right place in your head after first reading but also
> > allows you to quickly read just what you need.
> >
> > I'm now writing a library that I'd like to document very well, and info
> > files are my standard of excellence ;-).So I want to figure out a way
> > for creating such documentation with docutils, too.
>
> Documenting a library is different then a program, in my mind.  Or at
> least there should be some entirely thorough but not necessarily
> intuitively structured documentation.

True.

> In Webware I'm also making documents that are task and instruction
> oriented.  But they don't make up for the reference documentation that
> you want when you're already familiar with the library, or at least the
> concept behind the library, and you just want to know how to spell the
> method name or something.
>
> This is how I use the Python reference documentation -- which on the
> whole is quite good -- and is how I'd expect to use a docstring
> extractor.  I just write the other documents in a separate file.
>
Sure, if I write intorductory / how-to style docs, I'd want them out of my
source.  But it can be nice to place them together in one output file and
at least in info files, I never felt that these parts obstruct reference
reading in any way.

> > Now that I think of it, is anyone else interested in a GNU info writer
> > for docutils?  If yes, I'll append it to my task queue (i.e. don't
> > hold your breath).
>
> Info documents are often well organized, but the actual reader I've
> never been impressed with.  I get lost too easily.  But web pages
> certainly aren't ideal either.
>
It's much more impressive when you are restricted to a text terminal :-).
Besides, info is very handy in emacs.

> > This are closest to what I was doing.The module & class docstrings will
> > contain overview information, perhaphs even in many chapters, that would
> > link to relevant places in the low-level per-method documentation.
> >
> > The problem with this approach is that it relies too much on hyperlinks
> > for a good order of reading.The great thing about GNU info files is that
> > they are also organised in an order that is almost optimal for one-pass
> > front-to-back reading.Ian Bicking's idea is better because it allows you
> > to specify the order of the documentation entries differently from the
> > order of the code.
>
> I'm realizing that reordering the methods might be best anyway --
> usually they don't match up with the description because they were just
> written in a certain order.
>
> The whole hyperlinking thing I'm still unsure about.  I don't even know
> if there's a way to indicate that `references` should be turned into
> some sort of link.
>
The question is how files will be combined, so that a link in one file can
refence a section of another?  Perhaps in large projects, some sort of
top-level config file saying which files are processed and how are they
combined is needed.  Then, even when processing single files, the context
will be known to enable links processing.

Or maybe the "linking" model is better: individual files can be generated;
then, if you wish, you perform a linking stage to resolve links between
them.  Currently this implies buidling a single tree in memory of all the
docs.  Perhaps something like LaTeX's mechanisms for crossrefs should be
done: when a single file is processed, it emits an index file the link
targets it contains and resolves external links from other files.  You run
it several times to resolve all links.  OTOH, this sounds like overkill.

> > I think I see your idea.  But in many some cases this is short of
> > what's needed.  Consider (invented example) an application where many
> > classes contain special `gui_repr` methods that defines the user
> > interface for this object.  They are completely irrelevant to the
> > algorithms described in other methods, so a good manual will probably
> > separate the documentation of all GUI methods into a separate chapter
> > discussing them all at once.
>
> When you start getting into that level or organization you have to have
> an application-wide view for the document.  I'm just thinking of modules
> now -- but there certainly are many modules that aren't well contained.
>
If the code is organized well enough, you can put top-level glue docs in
the __init__.py of a packages.  If not, you need reorganisation again...

> > So I think there should be (optional) ways to specify reordering /
> > reorganisation of nodes.  I'm not sure how to do it in a convenient
> > yet flexible way.  Probably Python scripting to generate the
> > reorganisation info would do the trick but would not be equally
> > applicable to non-python-source uses of rST.
>
> I know... I've already thought of several packages I have that I'd like
> to autogenerate the documentation, but the format needs to be structured
> different from how it generally would be.  For instance, in one library
> I have error strings that can be overridden -- these could be extracted,
> but only by a program that understood how my specific code was
> structured.
>
> > Also, for big documentation, it would make sense to hold the user-only
> > parts in separate files, leaving only what's relevant to the source's
> > design in the source.  The current include directive might solve this
> > task too, if the reorganisation is applied later.
>
> I'm not sure what you mean here...?
>
Like what you said, that the introductory/task-oriented parts are better
stored in separate files.

-- 
Beni Cherniavsky <cb...@tx...>