Question

我使用Sphinx autosummary指令来记录一个类，但我遇到的问题是autosummary只是严格地显示了autosummary表中docstring的第一行。例如，

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

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

Answer 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是docstring 行列表。

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

在最初的大写字母后，句子不能包含额外的大写字母。
期后的空白字符。

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

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

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

在Sphinx autosummary中使用第一段而不是第一行

1 个答案: