Как связать методы str с помощью Sphinx?

Я использую Sphinx для создания своих HTML-документов из моих строк документации, как хороший маленький Pythonista.

У меня есть строка документации, которая выглядела так:

def do_a_thing(text):
    '''
    Call the ``str.strip()`` method on ``text``. Then do something
    else with it.
    '''

Однако я хочу, чтобы он ссылался на https://docs.python.org/3/library/stdtypes.html#str.strip, а не просто быть моноширинным и блочным.

Я пробовал несколько подходов:

:py:func:`str.strip()`
:mod:`str.strip()`
:class:`str.strip()`
:any:`str.strip()`
:doc:`str.strip()`

Ни один из них не работает, или, точнее, первые четыре подхода дают мне моноширинный и полужирный шрифт, но ни один из них на самом деле нигде не связан. И директива any дает мне WARNING: 'any' reference target not found: str.strip()

Очевидно, я мог бы сделать ссылку сам, но это кажется грубым и, вероятно, не совсем тем, что мне нужно, потому что что будет, когда я перейду на Python 4? Затем мне нужно обновить все мои ссылки в моей документации, и это просто ужасно.

Как правильно сослаться на документацию Python для метода str?


python python-sphinx docstring
person Wayne Werner    schedule 03.04.2017    source источник

Ответы (1)


arrow_upward
1
arrow_downward

Intersphinx ftw!

В conf.py добавьте пару строк. В документации Pyramid есть хорошие примеры добавления расширения Intersphinx. и настройка межсфинксовых сопоставлений.

extensions = [
    # ...
    'sphinx.ext.intersphinx',
    # ...
    ]

а также

intersphinx_mapping = {
    #...
    'python': ('https://docs.python.org/3', None),
    #...
}

Затем в ваших файлах .rst есть несколько способов указать на документы Python. Мы предпочитаем использовать следующий формат, который указывает автору документации, что ссылка будет разрешаться на указанный внешний источник документации.

:mod:`venv module <python:venv>`
:ref:`package <python:tut-packages>`

Для Python вы также можете использовать любую из директив внутри Домен Python, в том числе:

:py:meth:`str.strip`

Что касается управления версиями, вы можете использовать несколько имен в своем сопоставлении между сфинксами или обновлять целевое сопоставление.

intersphinx_mapping = {
    #...
    'python2': ('https://docs.python.org/2', None),
    'python': ('https://docs.python.org/3', None),  # use "python" for default version
    #...
}

или в будущем...

intersphinx_mapping = {
    #...
    'python2': ('https://docs.python.org/2', None),
    'python3': ('https://docs.python.org/3', None),
    'python': ('https://docs.python.org/4', None),  # use "python" for default version
    #...
}
person Steve Piercy    schedule 03.04.2017
comment
Итак, у меня уже был настроен интерсфинкс. Я попробовал <python:tut-packages>, и он ссылается на https://docs.python.org/3/tutorial/modules.html#tut-packages. Однако, если я вставлю туда <python:str.lstrip>, как в конце https://docs.python.org/3/library/stdtypes.html#str.lstrip, это не привяжет меня туда. - person Wayne Werner; 04.04.2017
comment
Я обновил свой ответ для вашего конкретного элемента. Для Python вы также можете использовать любую из директив внутри Домен Python, включая: :py:meth:str.strip - person Steve Piercy; 05.04.2017