Python Sphinx autodoc ไม่แสดงผลบน readthedocs
ฉันมีแพคเกจหลามโฮสต์บน Github เรียกspike2py ฉันเตรียมเอกสารโดยใช้ไฟล์ Sphinx และ. rst ไฟล์เหล่านี้เป็นโฮสต์บน GitHub ที่นี่ ฉันสามารถรันmake html
ในเครื่องได้สำเร็จและได้รับผลลัพธ์ที่ต้องการ นั่นคือส่วนคู่มืออ้างอิงของเอกสารประกอบไปด้วย API ที่สร้างขึ้นโดยอัตโนมัติโดยใช้ docstring ที่ฉันรวมไว้ในโค้ดของฉันและอ้างอิงโดยใช้การโทรไปยังautoclass
และautofunction
( reference_guide.rst )
ตัวอย่างเช่นต่อไปนี้เป็นลักษณะของส่วนแรกของคู่มืออ้างอิงเมื่อฉันแสดงผลในเครื่อง:
อย่างไรก็ตามเมื่อเอกสารถูกแสดงบนreadthedocs
( ดูที่นี่ ) คู่มืออ้างอิงจะไม่มีหลักที่แยกออกมา เฉพาะส่วนหัวที่พบในไฟล์. rst
พฤติกรรมที่คาดหวัง
ฉันคาดว่าเอกสารที่แสดงบน readthedocs จะเหมือนกับเอกสารที่แสดงในเครื่อง อย่างไรก็ตามสิ่งนี้ไม่เกิดขึ้น
เมื่อดูที่นี่ฉันได้ยืนยันว่าเวอร์ชันที่นำเสนอบน readthedocs ในเวอร์ชันปัจจุบันของเอกสารของฉัน
แต่เมื่อฉันพยายามดาวน์โหลดเอกสารในเวอร์ชัน PDF หรือ HTML คู่มืออ้างอิงจะไม่มี docstrings
ข้อมูลอื่น ๆ
ตามเอกสารที่อ่านแล้วไม่ควรส่งบิลด์โลคัลไปที่ GitHub เฉพาะไฟล์ต้นฉบับ
สิ่งนี้ค่อนข้างเกี่ยวข้องกับปัญหานี้แต่ฉันไม่สามารถทำให้โซลูชันที่เสนอใช้งานได้
อัปเดตฉันทำตามวิธีแก้ปัญหาที่แนะนำโดย Steve Piercy และส่วนนี้แก้ไขปัญหา ฉันเพิ่มdocs/requirements.txt
ไฟล์และ.readthedocs.yml
ไฟล์
ต่อมาฉันสังเกตเห็นว่าบิลด์ใช้ Python 3.7.9 เนื่องจากฉันใช้คำแนะนำประเภทจาก Python> = 3.8 ฉันต้องระบุเวอร์ชันของ Python ใน.readthedocs.yml
ไฟล์
จากนั้นฉันก็ติดอยู่กับโครงสร้าง RTD โดยบอกว่าไม่พบไฟล์ index.rst ของฉัน
Traceback (most recent call last):
File "/home/docs/checkouts/readthedocs.org/user_builds/spike2py/envs/latest/lib/python3.8/site-packages/sphinx/cmd/build.py", line 280, in build_main
app.build(args.force_all, filenames)
File "/home/docs/checkouts/readthedocs.org/user_builds/spike2py/envs/latest/lib/python3.8/site-packages/sphinx/application.py", line 348, in build
self.builder.build_update()
File "/home/docs/checkouts/readthedocs.org/user_builds/spike2py/envs/latest/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 297, in build_update
self.build(to_build,
File "/home/docs/checkouts/readthedocs.org/user_builds/spike2py/envs/latest/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 311, in build
updated_docnames = set(self.read())
File "/home/docs/checkouts/readthedocs.org/user_builds/spike2py/envs/latest/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 421, in read
raise SphinxError('master file %s not found' %
sphinx.errors.SphinxError: master file /home/docs/checkouts/readthedocs.org/user_builds/spike2py/checkouts/latest/docs/index.rst not found
Sphinx error:
master file /home/docs/checkouts/readthedocs.org/user_builds/spike2py/checkouts/latest/docs/index.rst not found
แต่จากนั้นฉันก็แก้ไขสิ่งนี้โดยระบุสิ่งต่อไปนี้ใน.readthedocs.yml
:
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/source/conf.py
หลังจากการแก้ไขนี้เอกสารจะถูกสร้างขึ้นด้วยสิ่งที่ดูเหมือนจะไม่มีข้อผิดพลาดและรวมถึงสิ่งต่อไปนี้:
generating indices... genindex py-modindexdone
highlighting module code... [ 20%] spike2py.channels
highlighting module code... [ 40%] spike2py.plot
highlighting module code... [ 60%] spike2py.read
highlighting module code... [ 80%] spike2py.sig_proc
highlighting module code... [100%] spike2py.trial
และใช่หลักคำสอนปรากฏบน RTD
คำตอบ
การอ้างอิงของโครงการของคุณไม่ได้ระบุไว้ใน RTD แต่คุณได้ติดตั้งการอ้างอิงในเครื่องแล้ว คุณสามารถตรวจสอบในการสร้างบันทึก ไปที่งานสร้างของโครงการของคุณคลิกงานสร้างแล้วคลิก "ดูข้อมูลดิบ"
WARNING: autodoc: failed to import class 'trial.TrialInfo' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'trial.Trial' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import function 'trial.load' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'channels.ChannelInfo' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'channels.Channel' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'channels.Event' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'channels.Keyboard' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'channels.Waveform' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'channels.Wavemark' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import class 'sig_proc.SignalProcessing' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import function 'plot.plot_channel' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import function 'plot.plot_trial' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
WARNING: autodoc: failed to import function 'read.read' from module 'spike2py'; the following exception was raised:
cannot import name 'Literal' from 'typing' (/home/docs/.pyenv/versions/3.7.9/lib/python3.7/typing.py)
ในการแก้ไขสถานการณ์คุณต้องระบุว่าต้องติดตั้งการอ้างอิงของโปรเจ็กต์ของคุณ ดูการระบุการอ้างอิง
คุณต้อง:
- สร้างไฟล์ข้อกำหนด pip ที่ระบุความต้องการหรือ
- สร้างไฟล์ที่ระบุ
pip install
อ็อพชันซึ่งจะติดตั้งข้อกำหนดที่กำหนดไว้แล้วในที่อื่นเช่นในsetup.py
docs_requires
stanza ดูตัวอย่างในที่เก็บพีระมิดกับrtd.txtและsetup.py
rtd.txt
-e .[docs]
setup.py
docs_extras = [
'Sphinx >= 3.0.0', # Force RTD to use >= 3.0.0
'docutils',
'pylons-sphinx-themes >= 1.0.8', # Ethical Ads
'pylons_sphinx_latesturl',
'repoze.sphinx.autointerface',
'sphinxcontrib-autoprogram',
]
# ...
extras_require={'testing': testing_extras, 'docs': docs_extras},
คุณได้กำหนดข้อกำหนดโครงการของคุณในไฟล์นี้จากนั้นคุณต้องกำหนดค่า Read the Docs เพื่อรับรู้ไฟล์นี้เพื่อติดตั้งการอ้างอิง วิธีที่แนะนำคือใช้ไฟล์คอนฟิกูเรชันแต่คุณสามารถทำได้ผ่านแดชบอร์ดผู้ดูแลระบบของโปรเจ็กต์
ฉันมีปัญหาเดียวกัน Readthedocs ไม่สามารถแยก docstrings จากโครงการของฉันได้เนื่องจากไม่พบโมดูลโครงการของฉัน
ฉันแก้ไขสิ่งนี้โดยเพิ่ม 2 เส้นทางสัมพัทธ์ใน docs / conf.py:
sys.path.insert(0, os.path.abspath("."))
sys.path.insert(0, os.path.abspath("../"))
เพื่อให้ตอนนี้ด้านบนของ docs / conf.py มีลักษณะดังนี้:
import os
import sys
import sphinx_rtd_theme
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath("."))
sys.path.insert(0, os.path.abspath("../"))
sys.path.insert(1, os.path.dirname(os.path.abspath("../")) + os.sep + "feature_engine")