CODEWITHSUNDEEP
pythonpython-sphinx
astrofrog
astrofrog

Reputation: 34091

Use first paragraph instead of first line in Sphinx autosummary

I am using the Sphinx autosummary directive to document a class, but I am running into the issue that autosummary only strictly shows the first line of the docstring in the autosummary table. For example,

.. currentmodule:: logging
.. autosummary::
  ~Logger.manager
  ~Logger.root

produces a table which has:

manager   There is [under normal circumstances] just one Manager instance, which
root      A root logger is not that different to any other logger, except that

I can understand why this is the default, but is there a way to make it so that the first sentence or the first paragraph are shown?

Upvotes: 4

Views: 637

Answers (1)

mzjn
mzjn

Reputation: 50947

Your docstrings apparently come from the standard library logging module. They look like this:

class Manager(object):
    """
    There is [under normal circumstances] just one Manager instance, which
    holds the hierarchy of loggers.
    """

and 

class RootLogger(Logger):
    """
    A root logger is not that different to any other logger, except that
    it must have a logging level and there is only one instance of it in
    the hierarchy.
    """

This is the code that returns the autosummary string (autosummary/__init__.py):

m = re.search(r"^([A-Z][^A-Z]*?\.\s)", " ".join(doc).strip())
if m:
    summary = m.group(1).strip()
elif doc:
    summary = doc[0].strip()
else:
    summary = '':

doc is the docstring as a list of lines.

The autosummary string is supposed to be the first sentence of the docstring. However, there are problems with the regular expression:

  1. After the initial uppercase letter, the sentence cannot contain additional uppercase letters.
  2. A whitespace character is expected after the period.

This means that the regular expression won't match any of the docstrings above. If the pattern is changed to 

^([A-Z].*?\.\s?)

then it will match both docstrings, and complete first sentences will appear in the output. (This may not be the optimal regex, but at least it works in this case.)

Upvotes: 2

Related Questions