Bagaimana cara saya menautkan ke metode str menggunakan Sphinx?

Saya menggunakan Sphinx untuk membuat dokumen HTML dari dokumen saya seperti Pythonista yang bagus.

Saya memiliki dokumen yang terlihat seperti ini:

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

Namun, saya ingin tautannya ke https://docs.python.org/3/library/stdtypes.html#str.strip daripada hanya monospace dan blok kode.

Saya sudah mencoba beberapa pendekatan:

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

Tak satu pun dari ini berhasil - atau lebih tepatnya, empat pendekatan pertama memberi saya tampilan font monospace & tebal, namun tidak satupun yang benar-benar tertaut ke mana pun. Dan arahan any memberi saya WARNING: 'any' reference target not found: str.strip()

Jelas saya dapat membuat tautan sendiri, tetapi itu tampak menjijikkan dan mungkin juga bukan yang saya inginkan, karena bagaimana jika saya meningkatkan ke Python 4? Lalu saya harus memperbarui semua tautan saya di dokumentasi saya dan itu menjijikkan.

Apa cara yang tepat untuk menautkan ke dokumentasi Python untuk metode str?


python python-sphinx docstring
person Wayne Werner    schedule 03.04.2017    source sumber

Jawaban (1)


arrow_upward
1
arrow_downward

Intersphinx ftw!

Di conf.py, tambahkan beberapa baris. Dokumentasi piramida memiliki contoh bagus untuk menambahkan ekstensi Intersphinx dan mengonfigurasi pemetaan intersphinx.

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

Dan

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

Kemudian di file .rst Anda, ada beberapa cara untuk menunjuk ke dokumen Python. Kami lebih suka menggunakan format berikut yang menunjukkan kepada penulis dokumentasi bahwa tautan akan mengarah ke sumber dokumentasi eksternal tertentu.

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

Untuk Python, Anda juga dapat menggunakan arahan apa pun dalam Domain Python, termasuk:

:py:meth:`str.strip`

Sejauh membuat versi, Anda dapat menggunakan beberapa nama dalam pemetaan intersphinx atau memperbarui pemetaan target.

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

atau di masa depan...

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
Jadi, saya sudah mengkonfigurasi intersphinx seperti itu. Saya mencoba <python:tut-packages> dan tertaut ke https://docs.python.org/3/tutorial/modules.html#tut-packages. Namun, jika saya memasukkan <python:str.lstrip> di sana, seperti yang ada di akhir https://docs.python.org/3/library/stdtypes.html#str.lstrip, itu tidak menghubungkan saya ke sana. - person Wayne Werner; 04.04.2017
comment
Saya memperbarui jawaban saya untuk item spesifik Anda. Untuk Python, Anda juga dapat menggunakan arahan apa pun dalam Domain Python, termasuk: :py:meth:str.strip - person Steve Piercy; 05.04.2017