Geek asks and answers

Use the first paragraph instead of the first line in Sphinx autosummary

I use the autosummary Sphinx directive to document the class, but I ran into the problem that autosummary only strictly shows the first row of the docking in the autostomy table. For instance,

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

creates a table that 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 value, but is there a way to make the first sentence or first paragraph appear?

+3
source share
1 answer

Your docstrings seem to come from the standard logging library . 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 string autosummary ( 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 docstring as a list of strings.

docstring. :

  • .
  • .

, .

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

-, . ( , .)

+2

More articles:


All Articles