Python Sphinx Autodoc wird auf Readthedocs nicht gerendert
Ich habe ein Python-Paket auf Github namens spike2py gehostet . Ich habe meine Dokumente mit Sphinx- und .rst-Dateien vorbereitet. Diese Dateien werden hier auf GitHub gehostet . Ich kann erfolgreich make html
lokal ausgeführt werden und die gewünschte Ausgabe erhalten. Das heißt, der Teil des Referenzhandbuchs der Dokumentation enthält die API, die automatisch mit der in meinem Code enthaltenen Dokumentzeichenfolge generiert und mit Aufrufen von autoclass
und autofunction
( reference_guide.rst ) referenziert wird .
So sieht beispielsweise der erste Teil des Referenzhandbuchs aus, wenn ich es lokal rendere:

Wenn die Dokumentation jedoch am readthedocs
( siehe hier ) gerendert wird , enthält das Referenzhandbuch keine extrahierten Lehren. Nur die Header in der ersten Datei.
Erwartetes Verhalten
Ich habe erwartet, dass die auf readthedocs gerenderten Dokumente mit den lokal gerenderten übereinstimmen. Dies geschieht jedoch nicht.
Indem ich hier nachschaue, habe ich bestätigt, dass die Version in der aktuellen Version meiner Dokumentation auf readthedocs präsentiert wird.
Wenn ich jedoch versuche, PDF- oder HTML-Versionen der Dokumentation herunterzuladen, enthält das Referenzhandbuch keine Dokumentzeichenfolgen.
Andere Information
Gemäß der readthedocs- Dokumentation sollten die lokalen Builds nicht an GitHub übertragen werden. nur die Quelldateien.
Dies hängt etwas mit diesem Problem zusammen , aber ich konnte die vorgeschlagene Lösung nicht zum Laufen bringen.
UPDATE Ich folgte der von Steve Piercy empfohlenen Lösung und löste damit einen Teil des Problems. Ich habe eine docs/requirements.txt
Datei sowie eine .readthedocs.yml
Datei hinzugefügt .
Als nächstes bemerkte ich, dass der Build Python 3.7.9 verwendete. Da ich Typhinweise aus Python> = 3.8 verwendete, musste ich die Version von Python in der .readthedocs.yml
Datei angeben .
Dann blieb ich beim RTD-Build hängen und sagte mir, dass meine index.rst-Datei nicht gefunden werden kann.
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
Aber ich habe das dann gelöst, indem ich Folgendes in meinem angegeben habe .readthedocs.yml
:
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/source/conf.py
Nach diesem Fix werden die Dokumente ohne Fehler erstellt und enthalten Folgendes:
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
Und ja, die Lehren erschienen auf FTE.
Antworten
Die Abhängigkeiten Ihres Projekts sind nicht in RTD angegeben, aber Sie haben die Abhängigkeiten lokal installiert. Sie können dies im Build-Protokoll überprüfen . Besuchen Sie die Builds Ihres Projekts, klicken Sie auf einen Build und dann auf "Roh anzeigen".
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)
Um die Situation zu beheben, müssen Sie angeben, dass die Abhängigkeiten Ihres Projekts installiert werden müssen. Siehe Festlegen von Abhängigkeiten .
Sie müssen entweder:
- Erstellen Sie eine Pip-Anforderungsdatei, die Anforderungen angibt , oder
- Erstellen Sie eine Datei, die eine
pip install
Option angibt, mit der Anforderungen installiert werden, die bereits an anderer Stelle definiert sind, z. B. in einersetup.py
docs_requires
Zeilengruppe. Sehen Sie sich ein Beispiel im Pyramid-Repository mit rtd.txt und setup.py an .
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},
Wenn Sie Ihre Projektanforderungen in dieser Datei definiert haben, müssen Sie Read the Docs konfigurieren, um diese Datei zu erkennen und Abhängigkeiten zu installieren. Die bevorzugte Methode ist die Verwendung einer Konfigurationsdatei. Sie können dies jedoch auch über das Admin-Dashboard des Projekts tun .
Ich hatte genau das gleiche Problem. Readthedocs konnte die Dokumentzeichenfolgen nicht aus meinem Projekt extrahieren, da mein Projektmodul nicht gefunden wurde.
Ich habe dies gelöst, indem ich 2 relative Pfade in die Datei docs / conf.py eingefügt habe:
sys.path.insert(0, os.path.abspath("."))
sys.path.insert(0, os.path.abspath("../"))
Damit sieht der obere Teil der Datei docs / conf.py nun wie folgt aus:
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")