AutoDoc de Python Sphinx no representa en LetThedocs -- python campo con python-sphinx campo con read-the-docs campo con autodoc camp Relacionados El problema

Python Sphinx autodoc not rendering on readthedocs


2
vote

problema

Español

Tengo un paquete de Python alojado en GitHub llamado spike2py . He preparado mis documentos usando archivos Sphinx y. Estos archivos están alojados en GitHub aquí . Soy capaz de ejecutar con éxito make html localmente y obtener la salida deseada. Es decir, la guía de referencia parte de la documentación contiene la API generada automáticamente utilizando el documento que he incluido en mi código, y se hace referencia utilizando llamadas a autoclass y autofunction ( referencia_guide.rst ).

Por ejemplo, aquí es lo que parece la primera parte de la guía de referencia cuando lo hago localmente:

ingrese la descripción de la imagen aquí

Sin embargo, cuando la documentación se presenta en readthedocs ( ver aquí ), la guía de referencia no contiene los doctramientos extraídos; Sólo los encabezados encontrados en el archivo .st.

comportamiento esperado

Esperaba que los documentos hicieran que Letthedocs sean los mismos que los prestados localmente. Sin embargo, esto no está sucediendo.

Al buscar aquí , he confirmado que la versión que se presenta en sexthedocs en el Versión actual de mi documentación.

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

otra información

Según el archivo lectura Documentación , las compilaciones locales no deben ser empujadas a GitHub; Sólo los archivos de origen.

Esto está un tanto relacionado con este problema , pero no pude hacer la solución propuesta.

actualización Seguí la solución recomendada por Steve Piercy y esta parte resuelta del problema. Añadí un archivo make html10 , así como un archivo make html111111.

A continuación, noté que la construcción estaba usando Python 3.7.9. Dado que estaba usando tipos de temas de Python & GT; = 3.8, tuve que especificar la versión de Python en el archivo make html12 .

Luego me quedé atrapado con la construcción de RTD diciéndome que no puedo encontrar mi archivo index.rst.

  1.1274875 3  

pero luego resolví esto especificando lo siguiente en mi 1.1274875 4 :

  1.1274875 5  

Después de esta solución, los documentos se construyen con lo que parece ser ningún error e incluye lo siguiente:

  1.1274875 6  

y sí, los doctramientos aparecieron en RTD.

Original en ingles

I have a Python package hosted on Github called spike2py. I have prepared my docs using Sphinx and .rst files. These files are hosted on GitHub here. I am able to successfully run make html locally and obtain the desired output. That is, the Reference Guide part of the documentation contains the API automatically generated using the docstring I have included in my code, and referenced using calls to autoclass and autofunction (reference_guide.rst).

For example, here is what the first part of the Reference Guide looks like when I render it locally:

enter image description here

However, when the documentation is rendered on readthedocs (see here), the Reference Guide does not contain the extracted doctrings; just the headers found in the .rst file.

Expected behaviour

I expected the docs rendered on readthedocs to be same as those rendered locally. However, this is not happening.

By looking here, I have confirmed that the version being presented on readthedocs in the current version of my documentation.

But when I try to download PDF or HTML versions of the documentation, the Reference Guide does not include the docstrings.

Other info

According to the readthedocs documentation, the local builds should not be pushed to GitHub; only the source files.

This is somewhat related to this issue, but I was not able to make the proposed solution work.

UPDATE I followed the solution recommended by Steve Piercy and this solved part of the problem. I added a docs/requirements.txt file as well as a .readthedocs.yml file.

Next I noticed that the build was using Python 3.7.9. Given that I was using type hints from Python >= 3.8, I had to specify the version of Python in the .readthedocs.yml file.

Then I was stuck with the RTD build telling me it can't find my index.rst file.

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  

But I then solved this by specifying the following in my .readthedocs.yml:

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

After this fix, the docs are built with what appears to be no errors and includes the following:

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  

And yes, the doctrings appeared on RTD.

           

Lista de respuestas

2
 
vote
vote
La mejor respuesta
 

Las dependencias de su proyecto no se especifican en RTD, pero ha instalado las dependencias a nivel local. Puede verificar esto en la la construcción de registro . Visite las compilaciones de su proyecto, haga clic en una compilación y haga clic en "Ver 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)   

Para remediar la situación, debe especificar que deben instalarse las dependencias de su proyecto. Consulte especificando dependencias .

Usted debe:

  1. Crear un Archivo de requisitos PIP que especifica los requisitos , o
  2. Cree un archivo que especifique una opción pip install7 que instalará los requisitos que ya están definidos en otros lugares, como en un setup.py docs_requires Stanza. Vea un ejemplo en el repositorio de la pirámide con su rtd.txt y < un href = "https://github.com/pylons/pyramid/blob/master/setup.py" rel = "nofollow noreferrer"> setup.py .

RTD.TXT

  for i in range(20):     if True:         test = i         print(test) #print(test) 0  

Setup.py

  for i in range(20):     if True:         test = i         print(test) #print(test) 111  

Uno Ha definido sus requisitos de proyecto en este archivo, debe configurar leer los documentos para reconocer este archivo para instalar dependencias. El método preferido es usar una archivo de configuración , pero usted También puede hacer esto a través de la Panel de administración del proyecto .

 

Your project's dependencies are not specified on RTD, but you have installed the dependencies locally. You can verify this in the build log. Visit your project's Builds, click a build, and click "view 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) 

To remedy the situation, you must specify that your project's dependencies must be installed. See Specifying Dependencies.

You must either:

  1. Create a pip requirements file that specifies requirements, or
  2. Create a file that specifies a pip install option which will install requirements that are already defined elsewhere, such as in a setup.py docs_requires stanza. See an example in the Pyramid repository with its rtd.txt and 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}, 

One you have defined your project requirements in this file, then you must configure Read the Docs to recognize this file to install dependencies. The preferred method is to use a configuration file, but you can also do this through the project's Admin Dashboard.

 
 
     
     
0
 
vote

Tuve exactamente el mismo problema. LetThedocs no pudo extraer los doces de mi proyecto porque no encontró mi módulo de proyecto.

He resuelto esto agregando 2 rutas relativas en los docs / conf.py:

  for i in range(20):     if True:         test = i         print(test) #print(test) 2  

para que ahora la parte superior de los docs / conf.py se vea la siguiente:

  for i in range(20):     if True:         test = i         print(test) #print(test) 3  
 

I had exactly the same problem. Readthedocs could not extract the docstrings from my Project because it did not find my project module.

I solved this by adding 2 relative paths in the docs/conf.py:

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

So that now the top of the docs/conf.py looks as follows:

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

Relacionados problema

0  sphinxcontontrib.programutput funciona localmente, no funciona en LetThedocs  ( Sphinxcontrib programoutput works locally doesnt work on readthedocs ) 
Estoy tratando de usar sphinxcontrib.programutput para documentar automáticamente el comando (setq org-capture-templates '( ("c" "Class" entry (file "...

105  ¿Cuál es la forma correcta de documentar un parámetro ** Kwargs?  ( What is the correct way to document a kwargs parameter ) 
Estoy usando sphinx y el complemento AutoDoc para generar la documentación de API para mis módulos de Python. Si bien puedo ver cómo documentar mejor los pa...

2  Uso de Esfinge dentro de un proyecto utilizando varios lenguajes de programación [CERRADO]  ( Using sphinx within a project using several programming languages ) 
cerrado . Esta pregunta debe ser más enfocado . Actualmente no está aceptando respuestas. ...

9  ¿Cómo se especifica un tipo para las variables en los doctos de Python para Sphinx?  ( How does one specify a type for variables in python docstrings for sphinx ) 
Puede especificar tipos de parámetros en Docstrings de Python como este: def __init__(self, canvas, segments): """Class constructor. :param canvas...

1  Skipping Type Sugerencias en la documentación  ( Skipping type hints in documentation ) 
Vamos a considerar la siguiente función: def f(x: int, y: int) -> int: """Get sum of two integers. Parameters ---------- x : int f...

1  Esfinge incluye descripciones de la biblioteca 'Código' donde no se supone que  ( Sphinx includes code library descriptions where its not supposed to ) 
Estoy trabajando en una documentación de una envoltura de Python alrededor de una aplicación PyOBJC con Sphinx. Sphinx Agrega una descripción confusa y no d...

30  Autodoc de Python Sphinx y miembros decorados  ( Python sphinx autodoc and decorated members ) 
Estoy intentando usar Sphinx para documentar mi clase de Python. Lo hago usando AutoDOC: .. autoclass:: Bus :members: Mientras recupera correctament...

17  AUTODOC ESFINX DA ADVERTENCIA: PY: Tarjeta de referencia de clase no encontrada: Tipo ADVERTENCIA  ( Sphinx autodoc gives warning pyclass reference target not found type warning ) 
Tengo algún código que usa un metaclase en Python. Pero cuando se ejecuta AutoDOC Sphinx, está dando el error: WARNING: py:class reference target not found...

1  ¿Cómo usar Sphinx Apidoc para documentar solo las clases de Python que se importan en __init__.py?  ( How to use sphinx apidoc to only document python classes that are imported in ) 
Actualmente estoy usando Apidoc para generar archivos .RST para mi documentación y luego usar AutoDoc en ellos. El problema es que mi paquete separa el código...

6  AutoSummary: ¿Cómo controlar qué métodos se utilizan en los documentos generados?  ( Autosummary how to control which methods are used in generated docs ) 
Estoy usando Sphinx para generar mi documentación y la extensión autosummary se encarga de generar pequeños talones para todas las clases no explícitamente ...




© 2022 respuesta.top Reservados todos los derechos. Centro de preguntas y respuestas reservados todos los derechos