L'autodoc di Python Sphinx non viene visualizzato su readthedocs

Question

Ho un pacchetto Python ospitato su Github chiamato spike2py . Ho preparato i miei documenti usando Sphinx e file .rst. Questi file sono ospitati su GitHub qui . Sono in grado di eseguire con successo make htmllocalmente e ottenere l'output desiderato. Vale a dire, la parte della documentazione della Guida di riferimento contiene l'API generata automaticamente utilizzando la docstring che ho incluso nel mio codice e referenziata utilizzando le chiamate a autoclasse autofunction( reference_guide.rst ).

Ad esempio, ecco come appare la prima parte della Guida di riferimento quando la renderizzo localmente:

Tuttavia, quando si esegue il rendering della documentazione readthedocs( vedere qui ), la Guida di riferimento non contiene la documentazione estratta; solo le intestazioni trovate nel file .rst.

Comportamento atteso

Mi aspettavo che i documenti resi su readthedocs fossero gli stessi di quelli resi localmente. Tuttavia, questo non sta accadendo.

Guardando qui , ho confermato che la versione presentata su readthedocs nella versione corrente della mia documentazione.

Ma quando provo a scaricare le versioni PDF o HTML della documentazione, la Guida di riferimento non include le docstrings.

Altre informazioni

Secondo la documentazione di readthedocs , le build locali non dovrebbero essere inviate a GitHub; solo i file di origine.

Ciò è in qualche modo correlato a questo problema , ma non sono stato in grado di far funzionare la soluzione proposta.

AGGIORNAMENTO Ho seguito la soluzione consigliata da Steve Piercy e questa ha risolto una parte del problema. Ho aggiunto un docs/requirements.txtfile oltre che un .readthedocs.ymlfile.

Successivamente ho notato che la build utilizzava Python 3.7.9. Dato che stavo usando i suggerimenti sul tipo da Python> = 3.8, ho dovuto specificare la versione di Python nel .readthedocs.ymlfile.

Poi sono rimasto bloccato con la build RTD che mi diceva che non riesce a trovare il mio file 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

Ma poi ho risolto il problema specificando quanto segue nel mio .readthedocs.yml:

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

Dopo questa correzione, i documenti vengono creati senza errori e includono quanto segue:

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

E sì, le dottrine sono apparse su RTD.

Answer 1

Le dipendenze del progetto non sono specificate su RTD, ma le dipendenze sono state installate localmente. Puoi verificarlo nel registro build . Visita le build del tuo progetto, fai clic su una build e fai clic su "visualizza raw".

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)

Per rimediare alla situazione, è necessario specificare che le dipendenze del progetto devono essere installate. Vedere Specifica delle dipendenze .

Devi:

1. Creare un file dei requisiti pip che specifichi i requisiti o
2. Creare un file che specifichi pip installun'opzione che installerà requisiti già definiti altrove, come in una setup.py docs_requiresstanza. Guarda un esempio nel repository Pyramid con i relativi rtd.txt e 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},

Dopo aver definito i requisiti del progetto in questo file, è necessario configurare Leggi i documenti per riconoscere questo file per installare le dipendenze. Il metodo preferito è utilizzare un file di configurazione , ma puoi farlo anche tramite il dashboard di amministrazione del progetto .

Answer 2

Ho avuto esattamente lo stesso problema. Readthedocs non ha potuto estrarre le docstrings dal mio progetto perché non ha trovato il modulo del mio progetto.

Ho risolto questo problema aggiungendo 2 percorsi relativi in ​​docs / conf.py:

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

In modo che ora la parte superiore di docs / conf.py sia la seguente:

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