Autodoc Python Sphinx tidak merender di readthedocs

Dec 29 2020

Saya memiliki paket Python yang dihosting di Github yang disebut spike2py . Saya telah menyiapkan dokumen saya menggunakan file Sphinx dan .rst. File-file ini dihosting di GitHub di sini . Saya berhasil menjalankan make htmlsecara lokal dan mendapatkan hasil yang diinginkan. Artinya, Panduan Referensi bagian dari dokumentasi berisi API yang dibuat secara otomatis menggunakan docstring yang telah saya sertakan dalam kode saya, dan direferensikan menggunakan panggilan ke autoclassdan autofunction( reference_guide.rst ).

Misalnya, inilah bagian pertama dari Panduan Referensi saat saya merendernya secara lokal:

Namun, ketika dokumentasi ditampilkan readthedocs( lihat di sini ), Panduan Referensi tidak berisi doktrin yang diekstrak; hanya header yang ditemukan di file .rst.

Perilaku yang diharapkan

Saya berharap dokumen yang dirender di readthedocs sama dengan yang dirender secara lokal. Namun, ini tidak terjadi.

Dengan melihat di sini , saya telah mengonfirmasi bahwa versi yang disajikan di readthedocs dalam versi terbaru dari dokumentasi saya.

Tetapi ketika saya mencoba mengunduh dokumentasi versi PDF atau HTML, Panduan Referensi tidak menyertakan docstrings.

Info lain

Menurut dokumentasi readthedocs , build lokal tidak boleh didorong ke GitHub; hanya file sumber.

Ini agak terkait dengan masalah ini , tetapi saya tidak dapat membuat solusi yang diusulkan berfungsi.

PEMBARUAN Saya mengikuti solusi yang direkomendasikan oleh Steve Piercy dan ini menyelesaikan bagian dari masalah. Saya menambahkan docs/requirements.txtfile serta .readthedocs.ymlfile.

Selanjutnya saya perhatikan bahwa build menggunakan Python 3.7.9. Mengingat bahwa saya menggunakan petunjuk tipe dari Python> = 3.8, saya harus menentukan versi Python dalam .readthedocs.ymlfile tersebut.

Kemudian saya terjebak dengan build RTD yang memberi tahu saya bahwa itu tidak dapat menemukan file index.rst saya.

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

Tapi saya kemudian menyelesaikan ini dengan menentukan yang berikut di saya .readthedocs.yml:

# Build documentation in the docs/ directory with Sphinx
sphinx:
  configuration: docs/source/conf.py

Setelah perbaikan ini, dokumen dibuat dengan apa yang tampaknya tidak ada kesalahan dan termasuk yang berikut ini:

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

Dan ya, doktrin itu muncul di RTD.

Jawaban

1 StevePiercy Dec 30 2020 at 17:08

Ketergantungan proyek Anda tidak ditentukan pada RTD, tetapi Anda telah memasang ketergantungan secara lokal. Anda dapat memverifikasi ini di log build . Kunjungi Build proyek Anda, klik build, dan klik "lihat mentah".

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)

Untuk memperbaiki situasi ini, Anda harus menentukan bahwa dependensi proyek Anda harus diinstal. Lihat Menentukan Dependensi .

Anda harus:

  1. Buat file persyaratan pip yang menentukan persyaratan , atau
  2. Buat file yang menentukan pip installopsi yang akan menginstal persyaratan yang sudah ditentukan di tempat lain, seperti di setup.py docs_requiresstanza. Lihat contoh di repositori Pyramid dengan rtd.txt dan 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},

Setelah Anda menetapkan persyaratan proyek Anda dalam file ini, maka Anda harus mengkonfigurasi Baca Dokumen untuk mengenali file ini untuk menginstal dependensi. Metode yang disukai adalah menggunakan file konfigurasi , tetapi Anda juga dapat melakukannya melalui Admin Dashboard proyek .

SoleG Jan 01 2021 at 20:54

Saya memiliki masalah yang persis sama. Readthedocs tidak dapat mengekstrak dokumen dari Proyek saya karena tidak menemukan modul proyek saya.

Saya menyelesaikan ini dengan menambahkan 2 jalur relatif di docs / conf.py:

sys.path.insert(0, os.path.abspath("."))
sys.path.insert(0, os.path.abspath("../"))

Sehingga sekarang bagian atas docs / conf.py terlihat seperti berikut:

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")