Python Sphinx autodoc no se procesa en readthedocs

Question

Tengo un paquete de Python alojado en Github llamado spike2py . He preparado mis documentos usando archivos Sphinx y .rst. Estos archivos están alojados en GitHub aquí . Puedo ejecutar con éxito make htmllocalmente y obtener el resultado deseado. Es decir, la parte de la Guía de referencia de la documentación contiene la API genera automáticamente utilizando la cadena de documentación que he incluido en mi código, y se hace referencia al uso de las llamadas autoclassy autofunction( reference_guide.rst ).

Por ejemplo, así es como se ve la primera parte de la Guía de referencia cuando la renderizo localmente:

Sin embargo, cuando la documentación se presenta en readthedocs( ver aquí ), la Guía de referencia no contiene las doctrinas extraídas; solo los encabezados que se encuentran en el archivo .rst.

Comportamiento esperado

Esperaba que los documentos renderizados en readthedocs fueran los mismos que los renderizados localmente. Sin embargo, esto no está sucediendo.

Al mirar aquí , he confirmado que la versión que se presenta en readthedocs en la versión actual de mi documentación.

Pero cuando intento descargar versiones en PDF o HTML de la documentación, la Guía de referencia no incluye las cadenas de documentación.

Otra información

Según la documentación de readthedocs , las compilaciones locales no deben enviarse a GitHub; solo los archivos fuente.

Esto está algo relacionado con este problema , pero no pude hacer que la solución propuesta funcionara.

ACTUALIZACIÓN Seguí la solución recomendada por Steve Piercy y esto resolvió parte del problema. Agregué un docs/requirements.txtarchivo y un .readthedocs.ymlarchivo.

Luego noté que la compilación estaba usando Python 3.7.9. Dado que estaba usando sugerencias de tipo de Python> = 3.8, tuve que especificar la versión de Python en el .readthedocs.ymlarchivo.

Luego me quedé atascado con la compilación RTD que me decía que no podía encontrar mi archivo 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

Pero luego resolví esto especificando lo siguiente en mi .readthedocs.yml:

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

Después de esta corrección, los documentos se compilan con lo que parece no ser ningún error e incluyen lo siguiente:

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

Y sí, las doctrinas aparecieron en RTD.

Answer 1

Las dependencias de su proyecto no están especificadas en RTD, pero las ha instalado localmente. Puede verificar esto en el registro de compilación . Visite las compilaciones de su proyecto, haga clic en una compilación y haga clic en "ver sin formato".

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)

Para remediar la situación, debe especificar que las dependencias de su proyecto deben estar instaladas. Consulte Especificación de dependencias .

Debes:

1. Cree un archivo de requisitos de pip que especifique los requisitos , o
2. Cree un archivo que especifique una pip installopción que instalará requisitos que ya están definidos en otro lugar, como en una setup.py docs_requiresestrofa. Vea un ejemplo en el repositorio Pyramid con su rtd.txt y 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},

Una vez que haya definido los requisitos de su proyecto en este archivo, debe configurar Leer los documentos para reconocer este archivo para instalar dependencias. El método preferido es utilizar un archivo de configuración , pero también puede hacerlo a través del Panel de administración del proyecto .

Answer 2

Tuve exactamente el mismo problema. Readthedocs no pudo extraer las cadenas de documentos de mi proyecto porque no encontró el módulo de mi proyecto.

Resolví esto agregando 2 rutas relativas en docs / conf.py:

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

De modo que ahora la parte superior de docs / conf.py tiene el siguiente aspecto:

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