在 Sphinx 自动摘要中使用第一段而不是第一行答案

【问题标题】：Use first paragraph instead of first line in Sphinx autosummary在 Sphinx 自动摘要中使用第一段而不是第一行
【发布时间】：2012-05-23 11:18:12
【问题描述】：

我正在使用Sphinx autosummary 指令来记录一个类，但我遇到了 autosummary 仅严格显示 autosummary 表中文档字符串的第一行的问题。例如，

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

生成一个表格，其中包含：

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

我可以理解为什么这是默认设置，但是有没有办法让它显示第一句或第一段？

【问题讨论】：

标签： python python-sphinx

【解决方案1】：

您的文档字符串显然来自标准库 logging 模块。它们看起来像这样：

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

和

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.
    """

这是返回自动摘要字符串 (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 是作为行列表的文档字符串。

自动摘要字符串应该是the first sentence of the docstring。但是，正则表达式存在问题：

在首字母大写之后，句子不能包含额外的大写字母。
在句点之后需要一个空白字符。

这意味着正则表达式不会匹配上面的任何文档字符串。如果模式更改为

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

然后它将匹配两个文档字符串，并且完整的第一句话将出现在输出中。（这可能不是最佳的正则表达式，但至少它在这种情况下有效。）

【讨论】：