повторные параметры с python sphinx - PullRequest
Новая
       15

повторные параметры с python sphinx

6 голосов
/ 30 ноября 2011

Я новичок в 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).

Ответы [ 2 ]

1 голос
/ 07 декабря 2012

Я не знаю ничего похожего на ваши :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 .

0 голосов
/ 08 апреля 2015

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

...