Python Sphinx Autodoc wird auf Readthedocs nicht gerendert

Dec 29 2020

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 htmllokal 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 autoclassund 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.txtDatei sowie eine .readthedocs.ymlDatei 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.ymlDatei 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

1 StevePiercy Dec 30 2020 at 17:08

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:

  1. Erstellen Sie eine Pip-Anforderungsdatei, die Anforderungen angibt , oder
  2. Erstellen Sie eine Datei, die eine pip installOption angibt, mit der Anforderungen installiert werden, die bereits an anderer Stelle definiert sind, z. B. in einer setup.py docs_requiresZeilengruppe. 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 .

SoleG Jan 01 2021 at 20:54

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