Может ли sphinx игнорировать определенные метки в docstrings python?

Question

Я документирую свой проект с помощью сфинкса и используя расширение sphinxcontrib.napoleon, которое позволяет мне использовать docstrings в стиле Google.

Вот функция от моего проекта

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) 

Когда я анализирую это с сфинкса-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 исключает, линии между линиями, которые соответствуют маркером регулярное выражение. Если строки не совпадают, итоговая 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).

Добавьте следующую строку в ваш проект Сфинкса 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.Затем слушатель получает возможность фильтровать docstring. В этом примере слушатель будет отбрасывать все между строками, которые соответствуют регулярному выражению ^.*IGNORE.*$, поэтому вам решать это выражение так, чтобы оно было достаточно определенным для вашего проекта, но не требует маркера, который добавляет слишком много шума.

(Примечание: Если все, что вам изменить ваш conf.py, сфинкс не подберет, что изменение, потому что doctree не изменился Поэтому убедитесь, что вы запустите make clean (или rm -rf _build/*), прежде чем строить свои документы снова.).