повторяющиеся параметры с python sphinx

Я новичок в python-sphinx и не могу найти ничего, касающегося следующего:

Предположим, у меня есть функции foo(a,b) и bar(a,c), так что параметр a имеет одинаковое описание для обеих функций.

Можно ли задокументировать a только один раз (скажем, в foo), а затем скопировать это описание в bar, чтобы не обновлять оба фрагмента текста, если что-то в описании a изменится?

Например, скажем, я документирую foo:

def foo(a,b,c):
    """
    a function description.

    :param a: a string, your name
    :param b: something else
    """

Что было бы здорово, так это что-то в документации bar, например:

def bar(a,c)
    """
    another function description.

    :inheritParams foo a: # somehow inherits a's description from foo
    :param c: description for parameter c.
    """

даже лучше, если бы это были foo(a,b,d) и bar(a,c,d) и я мог бы сделать (в документации bar):

:inheritParams foo:  # grabs a and d documentation from function foo
:param c: description for parameter c

иметь какие-либо описания параметров, общие с foo и bar, взятые из foo. То есть определение для a и d будет скопировано из foo, и мне придется документировать любые остатки (c).


parameters python-sphinx
person mathematical.coffee    schedule 30.11.2011    source источник

Ответы (2)


arrow_upward
1
arrow_downward

Я не знаю ничего похожего на ваши :inheritParams: идеи (хотя они мне нравятся!), но вы, вероятно, могли бы достичь основной цели (однократно задокументировав параметр), используя RestructuredText замены

По сути, вы бы установили определение замены примерно так:

.. |param_a_docs| <documentation here>

а затем сослаться на него из строки документации следующим образом:

def foo(a,b,c):
    """
    a function description.

    :param a: |param_a_docs|
    :param b: something else
    """

Это может быть немного сложно настроить правильно, так как вам нужно убедиться, что определение замены может быть найдено, а добавление строк документации в микс может сделать это нетривиальным.

Можно попробовать настроить определения подстановки в rst-epilog. .

person Kevin Horn    schedule 07.12.2012

arrow_upward
0
arrow_downward

Вы можете попробовать sphinx-paramlinks. Он не копирует документацию по параметрам из foo в bar, как вы просили, но создает гиперссылку на документацию по параметрам в foo.

person Stretch    schedule 08.04.2015