Overview

The pyTooling.Documentation package provides helper functions to work with doc-strings - the text a Python entity documents itself with.

splitDocString

splitDocString() dedents a doc-string with inspect.cleandoc() and returns its summary - the first paragraph - and its body - whatever follows the first blank line.

A doc-string of None yields two empty strings, and a single-paragraph doc-string yields an empty body, so a caller needs no special case for either.

It is a function rather than a decorator, because the same split serves three unrelated purposes: @InheritDocString expresses its merge strategies in it, extractVersionInformation() reads a package’s short description with it, and @testcase reads a testcase’s summary with it.

from pyTooling.Documentation import splitDocString

summary, body = splitDocString(MyClass.__doc__)

How long a summary may be

A summary is a single sentence, so it is length-limited. The default of MAXIMUM_SUMMARY_LENGTH characters leaves room for a sentence of the usual 120 columns plus an embedded link or other markup. A longer first paragraph is a body that lost its summary, and a DocumentationError says so.

Pass 0 where the limit doesn’t apply - which is what @InheritDocString does, because a base-class’ doc-string belongs to whoever wrote it and rejecting it would turn a documentation style issue into an ImportError in a package that merely derives from that class.

from pyTooling.Documentation import splitDocString

# Rejects a first paragraph longer than 200 characters.
summary, body = splitDocString(docString)

# Accepts any length.
summary, body = splitDocString(docString, maxSummaryLength=0)

# Any other bound.
summary, body = splitDocString(docString, maxSummaryLength=80)