CODEWITHSUNDEEP
pythonpython-sphinxdocstring
Wayne Werner
Wayne Werner

Reputation: 51807

How do I link to str methods using Sphinx?

I'm using Sphinx to generate my HTML docs from my docstrings like a good lil' Pythonista.

I have a docstring that looked like this:

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

However, I want it to link to https://docs.python.org/3/library/stdtypes.html#str.strip rather than just be all monospace and code-blocky.

I've tried a couple of approaches:

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

None of these work - or more accurately, the first four approaches give me a monospaced & bolded font face, but none of them actually link anywhere. And the any directive gives me WARNING: 'any' reference target not found: str.strip()

Obviously I could make a link myself, but that seems gross and also probably not exactly what I want, because what about when I upgrade to Python 4? Then I have to update all of my links in my documentation and that's just gross.

What's the proper way to link to the Python documentation for a str method?

Upvotes: 2

Views: 666

Answers (1)

Steve Piercy
Steve Piercy

Reputation: 15045

Intersphinx ftw!

In conf.py, add a couple of lines. Pyramid documentation has good examples for adding the Intersphinx extension and configuring intersphinx mappings.

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

and

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

Then in your .rst files, there are several ways to point to the Python docs. We prefer to use the following format which indicates to the documentation author that the link will resolve to a specified external documentation source.

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

For Python, you can also use any of the directives within the Python Domain, including:

:py:meth:`str.strip`

As far as versioning, you can use multiple names in your intersphinx mapping or update the target mapping.

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

or in the future...

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
    #...
}

Upvotes: 1

Related Questions