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

[Ian Bicking]

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:
    """
    yada yada.  Pay particular attention to the `bar` method.

    .. inline: bar
    """

    def bar(self):
        """and so on..."""

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.

  Ian