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

Ian Bicking ianb@colorstudy.com
26 May 2003 14:46:17 -0500


On Mon, 2003-05-26 at 04:44, Beni Cherniavsky wrote:
> 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.

Like maybe, say:

.. inline Foo

(stuff taken from Foo's docstring)

.. end inline

And instead of making this a directive, it is a pre-compiler, where
everything between ".. inline Foo" and ".. end inline" is derivative
(and so shouldn't be edited, but can be read).

Of course, it should support more than just inlining docstrings, as
there's already two other examples of inlining that we want to use, and
no doubt more are likely.  

But it is a little crude to use a preprocessor.  That seems integral,
though, without some sort of powerful IDE that dynamically inlined such
documentation.

  Ian