[Doc-SIG] Re: [Tutor] Documentation concerns.

Beni Cherniavsky cben@techunix.technion.ac.il
Wed May 28 18:59:43 2003


Ian Bicking wrote on 2003-05-26:

> On Mon, 2003-05-26 at 01:03, grubert@users.sourceforge.net wrote:
> > a possible split would be:
> >
> > * the module reference is in docstrings
> > * there might be a user manaual for bigger ones
> > * and even a (maybe two) tutorials for large ones.
>
> In a similar One thing I've played with is being able to reference the
> docstrings, so you can put some reference information in the docstrings,
> and then inline those into the documentation.  I played around with a
> reST hack that did something like:
>
> # module docstring:
> """
> The foo module provides X, Y, and Z, but all functionality is provided
> through the `Foo` class:
>
> .. inline: Foo
> """
>
> class Foo:
>     #snipped...
>
> Another option might be to use such inlining in the external document.
> Then you can interject narrative, reorder and exclude things, but you
> avoide duplicate documentation.
>
> For another document, I've been using something that strips examples
> from a script (marked with special comments), and turns them into
> highlighted source snippets that can be included.  Kind of a similar
> idea.
>
Having all info inside the document itself is better because when
editing you can see it all.  If the docstrings are included later, you
might not notice when they change and the documentation can get out of
sync.  Even if the docstrings and the exrnal doc don't conradict each
other, it's harder to ensure that they cover all material without gaps
or too much overlap.  Of course, it's good practice to render the
final documentation and read it from time to time but you woulnd't do
it every 2 minutes, right?

I think the best solution is to have a tool that includes the
docstrings into your source while leaving some markers around it, so
that it is idempotent when run upon its own output.  Then you can
directly edit this output like it would appear at the end but you can
sync it to the docstrings at any moment by re-running the tool.

Supporting evidence: I'm now working on a reST document that includes
examples of logical-order strings and the result of applying the
unicode bidi algorithm on them.  Doing it manually would be
error-prone.  So I wrote a python script that leaves all unrecognized
text as-is but recomputes the visual-order results from the logical
order inputs and bound a key in emacs to filtering the region with it.
Now it's extremely convenient because I can see when writing what
precisely will the example teach my reader and things can't get out of
sync...

-- 
Beni Cherniavsky <cben@users.sf.net>