Python Sphinx autodoc okunan metinlerde işlenmiyor

Question

Github'da spike2py adında bir Python paketim var . Dokümanlarımı Sphinx ve .rst dosyalarını kullanarak hazırladım. Bu dosyalar burada GitHub'da barındırılıyor . make htmlYerel olarak başarılı bir şekilde çalışabiliyorum ve istenen çıktıyı elde edebiliyorum . Diğer bir deyişle, belgelerin Başvuru Kılavuzu kısmı, koduma dahil ettiğim ve autoclassve autofunction( reference_guide.rst ) çağrılarını kullanarak başvurduğum docstring kullanılarak otomatik olarak oluşturulan API'yi içerir .

Örneğin, yerel olarak oluşturduğumda Başvuru Kılavuzunun ilk bölümü şöyle görünüyor:

Bununla birlikte, dokümantasyon oluşturulduğunda readthedocs( buraya bakın ), Referans Kılavuz, çıkarılan dokümanları içermez; .rst dosyasında bulunan başlıklar.

Beklenen davranış

Okunan dokümanlar üzerinde oluşturulan dokümanların yerel olarak oluşturulanlarla aynı olmasını bekliyordum. Ancak bu olmuyor.

Buraya bakarak , dokümantasyonumun güncel versiyonunda okunan dokümanlar üzerinde sunulan versiyonun olduğunu doğruladım.

Ancak belgelerin PDF veya HTML sürümlerini indirmeye çalıştığımda, Başvuru Kılavuzu belge dizilerini içermiyor.

Diğer bilgiler

Readthedocs belgelerine göre , yerel yapılar GitHub'a gönderilmemelidir; yalnızca kaynak dosyalar.

Bu biraz bu konuyla ilgili ancak önerilen çözümün işe yaramasını sağlayamadım.

GÜNCELLEME Steve Piercy tarafından önerilen çözümü takip ettim ve bu sorunun bir kısmını çözdü. Bir docs/requirements.txtdosyanın yanı sıra bir .readthedocs.ymldosya ekledim .

Sonra yapının Python 3.7.9 kullandığını fark ettim. Python> = 3.8'den tür ipuçlarını kullandığım için, .readthedocs.ymldosyada Python sürümünü belirtmem gerekiyordu .

Sonra RTD yapısına takılıp, index.rst dosyamı bulamadığını söyledim.

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

Ama sonra bunu, aşağıdakileri belirterek çözdüm .readthedocs.yml:

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

Bu düzeltmeden sonra, belgeler hatasız gibi görünenlerle oluşturulur ve aşağıdakileri içerir:

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

Ve evet, doktrinler RTD'de yayınlandı.

Answer 1

Projenizin bağımlılıkları RTD'de belirtilmemiştir, ancak bağımlılıkları yerel olarak yüklediniz. Bunu yapı günlüğünde doğrulayabilirsiniz . Projenizin Yapılarını ziyaret edin, bir yapıyı tıklayın ve "ham görüntüle" yi tıklayın.

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)

Durumu düzeltmek için, projenizin bağımlılıklarının yüklenmesi gerektiğini belirtmelisiniz. Bkz . Bağımlılıkları Belirleme .

Şunlardan birini yapmalısınız:

1. Gereksinimleri belirten bir pip gereksinimleri dosyası oluşturun veya
2. pip installBir setup.py docs_requiresstanza gibi başka bir yerde zaten tanımlanmış gereksinimleri yükleyecek bir seçeneği belirten bir dosya oluşturun . Pyramid deposundaki rtd.txt ve setup.py ile bir örneğe bakın .

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},

Bu dosyada proje gereksinimlerinizi tanımladıysanız, bağımlılıkları yüklemek için bu dosyayı tanıması için Belgeleri Oku özelliğini yapılandırmanız gerekir. Tercih edilen yöntem bir yapılandırma dosyası kullanmaktır , ancak bunu projenin Yönetici Gösterge Tablosu aracılığıyla da yapabilirsiniz .

Answer 2

Ben tam olarak aynı problem vardı. Readthedocs proje modülümü bulamadığı için projemden docstrings'i çıkaramadı.

Bunu docs / conf.py içine 2 göreli yol ekleyerek çözdüm:

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

Böylece, şimdi docs / conf.py'nin üst kısmı aşağıdaki gibi görünüyor:

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