sphinx 可以忽略 python 文档字符串中的某些标签吗？

Question

我正在使用 sphinx 记录我的项目，并使用 sphinxcontrib.napoleon 扩展，它允许我使用谷歌风格的文档字符串。

这是我的项目中的一个函数

def nn_normalized_weight(normweight_fn, qaid2_nns, qreq_):
    """
    Weights nearest neighbors using the chosen function

    Args:
        normweight_fn (func): chosen weight function e.g. lnbnn
        qaid2_nns (dict): query descriptor nearest neighbors and distances. qaid -> (qfx2_nnx, qfx2_dist)
        qreq_ (QueryRequest): hyper-parameters

    Returns:
        tuple(dict, dict) : (qaid2_weight, qaid2_selnorms)

    Example:
        >>> from ibeis.model.hots.nn_weights import *
        >>> from ibeis.model.hots import nn_weights
        >>> ibs, daid_list, qaid_list, qaid2_nns, qreq_ = nn_weights.testdata_nn_weights()
        >>> qaid = qaid_list[0]
        >>> #----
        >>> normweight_fn = lnbnn_fn
        >>> tup1 = nn_weights.nn_normalized_weight(normweight_fn, qaid2_nns, qreq_)
        >>> (qaid2_weight1, qaid2_selnorms1) = tup1
        >>> weights1 = qaid2_weight1[qaid]
        >>> selnorms1 = qaid2_selnorms1[qaid]
        >>> #---
        >>> # test NN_WEIGHT_FUNC_DICT
        >>> #---
        >>> nn_normonly_weight = nn_weights.NN_WEIGHT_FUNC_DICT['lnbnn']
        >>> tup2 = nn_normonly_weight(qaid2_nns, qreq_)
        >>> (qaid2_weight2, qaid2_selnorms2) = tup2
        >>> selnorms2 = qaid2_selnorms2[qaid]
        >>> weights2 = qaid2_weight2[qaid]
        >>> assert np.all(weights1 == weights2)
        >>> assert np.all(selnorms1 == selnorms2)

    Ignore:
        #from ibeis.model.hots import neighbor_index as hsnbrx
        #nnindexer = hsnbrx.new_ibeis_nnindexer(ibs, daid_list)
    """
    #utool.stash_testdata('qaid2_nns')
    #
    K = qreq_.qparams.K

    Knorm = qreq_.qparams.Knorm
    rule  = qreq_.qparams.normalizer_rule
    # Prealloc output
    qaid2_weight = {qaid: None for qaid in six.iterkeys(qaid2_nns)}
    qaid2_selnorms = {qaid: None for qaid in six.iterkeys(qaid2_nns)}
    # Database feature index to chip index
    for qaid in six.iterkeys(qaid2_nns):
        (qfx2_idx, qfx2_dist) = qaid2_nns[qaid]
        # Apply normalized weights
        (qfx2_normweight, qfx2_normmeta) = apply_normweight(
            normweight_fn, qaid, qfx2_idx, qfx2_dist, rule, K, Knorm, qreq_)
        # Output
        qaid2_weight[qaid]   = qfx2_normweight
        qaid2_selnorms[qaid] = qfx2_normmeta
    return (qaid2_weight, qaid2_selnorms)

当我用 sphinx-apidoc 解析它时，它会正确解析参数、返回和示例部分，但它也会在忽略部分上标记。

忽略部分看起来非常难看，因为它的所有格式都被删除了。我想将其删除。有没有办法配置 sphinx 来忽略某些标签，例如 Ignore:？

我知道我可以从 docstr 中取出它，但这非常不方便，因为我想有一个不带 # sybmols 的地方，我可以在 ipython 之间复制和粘贴测试代码。

Answer 1

好吧，我想我已经为你找到了一个解决方案：

sphinx.ext.autodoc提供一个监听器sphinx.ext.autodoc.between，可用于确定autodoc应保留或丢弃文档字符串收集的哪些部分：

sphinx.ext.autodoc.between(marker, what=None, keepempty=False, exclude=False)

返回一个侦听器，该侦听器保留或排除（如果排除）与标记True正则表达式匹配的行之间的行。如果没有行匹配，则生成的文档字符串将为空，因此除非keepempty为 true，否则不会进行任何更改。

如果What是字符串序列，则仅处理What中类型的文档字符串。

sphinxcontrib.napoleonautodoc适用于收集的文档字符串napoleon，因此这也应该适用。

使用示例

像这样更改您的文档字符串：

"""
Args:
    ...

Returns:
    ...

IGNORE:
    #from ibeis.model.hots import neighbor_index as hsnbrx
    #nnindexer = hsnbrx.new_ibeis_nnindexer(ibs, daid_list)
IGNORE
"""

因此，请确保用包含唯一标记的两行包围要排除的部分（在本例中为大写单词IGNORE）。

将以下内容添加到您的 Sphinx 项目中conf.py（我可能会将其作为一个块全部附加在底部，但这是您的决定）：

from sphinx.ext.autodoc import between

def setup(app):
    # Register a sphinx.ext.autodoc.between listener to ignore everything
    # between lines that contain the word IGNORE
    app.connect('autodoc-process-docstring', between('^.*IGNORE.*$', exclude=True))
    return app

（如果您conf.py已经包含setup()函数，只需相应地扩展它）。

这将创建并注册一个侦听器，每次autodoc处理文档字符串时都会调用该侦听器。然后，侦听器有机会过滤文档字符串。在此示例中，侦听器将丢弃与正则表达式匹配的行之间的所有内容^.*IGNORE.*$- 因此您可以选择此表达式，以便它对于您的项目足够具体，但不需要添加太多噪音的标记。

（注意：如果您所做的所有更改都是您的conf.py，Sphinx 将不会接受该更改，因为文档树没有更改。因此，请确保在再次构建文档之前运行make clean（或））。rm -rf _build/*