ฉันจะลิงก์ไปยังวิธี str โดยใช้ 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

อินเตอร์สฟิงซ์ ftw!

ใน conf.py ให้เพิ่มสองสามบรรทัด เอกสารประกอบของพีระมิดมีตัวอย่างที่ดีสำหรับการเพิ่ม ส่วนขยาย 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