__doc__+= """Detailed description"""

[Ben Finney]

pa at see.signature.invalid (Pierre Asselin) writes:

> Hi.  Started using python a few months back, still settling on my
> style.

Welcome! Please consider your part in the Python community, and found
your style on PEP 8 <URL:http://www.python.org/dev/peps/pep-0008/>, the
Style Guide for Python Code.

> I write docstrings and I use "pydoc mymodule" to refresh my memory.

Excellent. Please conform to the Docstring Conventions of PEP 257
<URL:http://www.python.org/dev/peps/pep-0257/>.

> Problem: if I just docstring my classes/methods/functions the output
> of pydoc more or less works as a reference manual

Hmm. That doesn't sound like a good use for docstrings. They are
reference material, but very focussed; a “reference manual” sounds much
more comprehensive and isn't well suited to docstrings, in my opinion.

> but if I get sidetracked for even a few weeks I find that
> documentation inadequate when I return to my code.

Yes, that would be a natural outcome of trying to make docstrings too
large. There are other forms of documentation available, such as a
separate reference manual, that you could write as well.

> Wery well, write a module docstring then. The problem now: the many
> paragraphs of detailed description at the top of the module get in the
> way. The pydoc output is good, but the code becomes hard to read.

So don't put so much into the module docstring. Your module should
consist of many smaller pieces, mainly classes and functions. Document
the specifics in those more local docstrings.

> So I come up with this:
>
> ######################################################################
>     #! env python
>
>     """One-liner docstring."""
>
>     # Many classes, methods, functions, attributes,
>     # with docstrings as needed.  Docs tend to be
>     # short and the code speaks for itself.
>     # ...
>     # Much further down,
>
>     ___doc___+= """
>
>     Detailed description goes here.  Provide some context,
>     explain what the classes are for and what the most important
>     methods are, give simple examples, whatever.  Say enough
>     to make the rest understandable."""

I'm having trouble imagining what would need to be put in that separate
chunk of docstring. Can you point to real code online that uses this
style?

>     if __name__ == "__main__":
>         # test code follows

As an aside, if your modules are complex, this style of test code is
likely to be too big for shoving into the same module, and too brittle
written this way.

Instead, make lots of distinct, focussed unit tests using the ‘unittest’
module, and make other kinds of tests (e.g. feature tests) using other
frameworks – leaving the actual implementation code clear of this cruft.

> It seems to work, too.  But is that a sound way to write python?
> Am I relying on undocumented implementation details or am I safe?

I think you're trying to make one file do everything, which is ignoring
the better organisation that multiple files can make.

> I guess I am trying to control the order of exposition without
> resorting to full-fledged Literate Programming.

Yes. Maybe you need to let go of this need to control the order in which
the reader views your code; we're going to be looking at small, focussed
parts anyway, not reading the whole thing in one go. So work with that
instead.

-- 
 \        “There are only two ways to live your life. One is as though |
  `\          nothing is a miracle. The other is as if everything is.” |
_o__)                                                 —Albert Einstein |
Ben Finney