Python Sphinx autodoc ไม่แสดงผลบน readthedocs

Dec 29 2020

ฉันมีแพคเกจหลามโฮสต์บน 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

คำตอบ

1 StevePiercy Dec 30 2020 at 17:08

การอ้างอิงของโครงการของคุณไม่ได้ระบุไว้ใน 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)

ในการแก้ไขสถานการณ์คุณต้องระบุว่าต้องติดตั้งการอ้างอิงของโปรเจ็กต์ของคุณ ดูการระบุการอ้างอิง

คุณต้อง:

  1. สร้างไฟล์ข้อกำหนด pip ที่ระบุความต้องการหรือ
  2. สร้างไฟล์ที่ระบุpip installอ็อพชันซึ่งจะติดตั้งข้อกำหนดที่กำหนดไว้แล้วในที่อื่นเช่นในsetup.py docs_requiresstanza ดูตัวอย่างในที่เก็บพีระมิดกับ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 เพื่อรับรู้ไฟล์นี้เพื่อติดตั้งการอ้างอิง วิธีที่แนะนำคือใช้ไฟล์คอนฟิกูเรชันแต่คุณสามารถทำได้ผ่านแดชบอร์ดผู้ดูแลระบบของโปรเจ็กต์

SoleG Jan 01 2021 at 20:54

ฉันมีปัญหาเดียวกัน 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")