Как ссылаться на документированный параметр функции Python с помощью разметки Sphinx?

Question

Я хотел бы ссылаться на ранее зарегистрированный параметр функции в другом месте в docstring Python. Рассмотрим следующий (по общему признанию, полностью искусственный) пример:

def foo(bar): 
    """Perform foo action 
    :param bar: The bar parameter 
    """ 

    def nested(): 
     """Some nested function that depends on enclosing scope's bar parameter. 
     I'd like to reference function foo's bar parameter here 
     with a link, is that possible?""" 
     return bar * bar 

    # ... 
    return nested() 

есть простой способ вставлять ссылки параметр, используя Sphinx разметку, или это будет происходить автоматически?

(Я полный Sphinx новичок. Я сканируя документы Сфинкса и не нашел ответ на этот вопрос, или пример, демонстрирующий правильную разметку.)

Answer 1

Я только что построил расширение, чтобы выполнить эту задачу. До сих пор он, похоже, работал с автономной HTML-сборкой и дополнительно с readthedocs (после некоторых дополнительных настроек).

расширение доступно по адресу: https://pypi.python.org/pypi/sphinx-paramlinks/.

Я вывожу его прямо сейчас для проектов Alembic и SQLAlchemy. (sample).

Я принимаю несогласие с предложением, что ссылка на params означает, что документы слишком длинны. Стандартная библиотека Python является плохим примером здесь, поскольку функции stdlib обязательно являются гранулированными и простыми. Программное обеспечение, которое выполняет более крупномасштабную задачу, когда одна функция проходит поверх сложной проблемы, которая будет решена, часто будет иметь параметры, требующие гораздо большего объяснения; это объяснение часто весьма ценно, поскольку решение конкретной проблемы в другом месте и, следовательно, возможность связать с ней очень важно.

Answer 2

Если вы ищете способ ссылки непосредственно на определение barfoo, то ваша документация слишком длинная или вы просите вашего читателя игнорировать лес для одного дерева или некоторую комбинацию из двух.

Принимая пример из defaultdict Examples:

Setting the :attr:`default_factory` to :class:`int` makes the 
:class:`defaultdict` useful for counting (like a bag or multiset in other 
languages): 

, если я не могу быть обеспокоен, чтобы прочитать пять предложений в collections.defaultdict найти смысл default_factory я, вероятно, не заслуживают того, чтобы быть там вести.

Обратите внимание, что ссылка атрибута Синтаксис такой же, как и в предыдущем разделе:

The first argument provides the initial value for the :attr:`default_factory` 
attribute; it defaults to ``None``. 

, но это выглядит как сфинкс не доходит из текущей области раздела и поэтому делает позднюю ссылку как стилизованный текст а не как якорь. Меня это не удивило бы, если бы это было намеренно.

Answer 3

Нет простого способа получить прямую ссылку на параметр функции с sphinx, и я не знаю расширения для этой проблемы.

documentation of the python domain объясняет, какие объекты могут быть перекрестными.

Возможный способ дать пользователю ссылку на параметр bar функции foo будет

See parameter ``bar`` in :func:`foo`. 

Возможно прямое указание было бы возможно, написав расширение.