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解析它时它正确地解析了args，return和example部分，但是它也在ignore部分标记了。

忽略部分看起来非常难看，因为它已经剥离了所有的格式。我想删除它。有没有办法配置sphinx忽略忽略某些标签：？

我知道我可以把它从docstr中取出来，但是这非常不方便，因为我想要一个没有领导#symmols的地方，我可以在ipython中复制和粘贴测试代码。

Answer 1

好的，我想我已经找到了解决方案：

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

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

返回一个监听器，该监听器要么保留，要么 exclude 是True排除的行之间的行   匹配标记正则表达式。如果没有匹配行，则生成的docstring将为空，因此除非 keepempty 为真，否则不会进行任何更改。

如果是一系列字符串，则只会处理内容中类型的文档字符串。

sphinxcontrib.napoleon works on the docstrings that autodoc collects，因此这也适用于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处理文档字符串时调用的侦听器。然后，监听器有机会过滤docstring。在此示例中，侦听器将丢弃与正则表达式^.*IGNORE.*$匹配的行之间的所有内容 - 因此，您可以选择此表达式，以便它对您的项目足够具体，但不需要添加的标记噪音很大。

（注意：如果您更改的是conf.py，那么Sphinx将不会接受该更改，因为该doctree没有更改。所以请确保您运行{{1}在再次构建文档之前（或make clean）。

sphinx可以忽略python docstrings中的某些标签吗？

1 个答案: