L'autodoc Python Sphinx ne s'affiche pas sur readthedocs
J'ai un package Python hébergé sur Github appelé spike2py . J'ai préparé mes documents en utilisant des fichiers Sphinx et .rst. Ces fichiers sont hébergés sur GitHub ici . Je suis capable d'exécuter avec succès make html
localement et d'obtenir le résultat souhaité. Autrement dit, la partie Guide de référence de la documentation contient l'API générée automatiquement à l'aide de la docstring que j'ai incluse dans mon code et référencée à l'aide d'appels à autoclass
et autofunction
( reference_guide.rst ).
Par exemple, voici à quoi ressemble la première partie du Guide de référence lorsque je le rende localement:

Cependant, lorsque la documentation est rendue sur readthedocs
( voir ici ), le Guide de référence ne contient pas les doctrings extraits; juste les en-têtes trouvés dans le fichier .rst.
Comportement attendu
Je m'attendais à ce que les documents rendus sur readthedocs soient les mêmes que ceux rendus localement. Cependant, cela ne se produit pas.
En regardant ici , j'ai confirmé que la version présentée sur readthedocs dans la version actuelle de ma documentation.
Mais lorsque j'essaye de télécharger des versions PDF ou HTML de la documentation, le Guide de référence n'inclut pas les docstrings.
Autre info
Selon la documentation readthedocs , les builds locaux ne doivent pas être poussés vers GitHub; seuls les fichiers source.
C'est un peu lié à ce problème , mais je n'ai pas été en mesure de faire fonctionner la solution proposée.
MISE À JOUR J'ai suivi la solution recommandée par Steve Piercy et cela a résolu une partie du problème. J'ai ajouté un docs/requirements.txt
fichier ainsi qu'un .readthedocs.yml
fichier.
Ensuite, j'ai remarqué que la construction utilisait Python 3.7.9. Étant donné que j'utilisais des indices de type de Python> = 3.8, j'ai dû spécifier la version de Python dans le .readthedocs.yml
fichier.
Ensuite, je me suis retrouvé coincé avec la version RTD en me disant qu'elle ne pouvait pas trouver mon fichier 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
Mais j'ai ensuite résolu ce problème en spécifiant ce qui suit dans mon .readthedocs.yml
:
# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/source/conf.py
Après ce correctif, les documents sont créés avec ce qui ne semble pas être d'erreur et comprend les éléments suivants:
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
Et oui, les doctrings sont apparus sur RTD.
Réponses
Les dépendances de votre projet ne sont pas spécifiées sur RTD, mais vous avez installé les dépendances localement. Vous pouvez le vérifier dans le journal de construction . Visitez les builds de votre projet, cliquez sur une build et cliquez sur "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)
Pour remédier à la situation, vous devez spécifier que les dépendances de votre projet doivent être installées. Voir Spécification des dépendances .
Vous devez soit:
- Créez un fichier d'exigences pip qui spécifie les exigences , ou
- Créez un fichier qui spécifie une
pip install
option qui installera des exigences déjà définies ailleurs, comme dans unesetup.py
docs_requires
strophe. Voir un exemple dans le référentiel Pyramid avec ses rtd.txt et 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},
Une fois que vous avez défini les exigences de votre projet dans ce fichier, vous devez configurer Read the Docs pour reconnaître ce fichier et installer les dépendances. La méthode préférée consiste à utiliser un fichier de configuration , mais vous pouvez également le faire via le tableau de bord d'administration du projet .
J'ai eu exactement le même problème. Readthedocs n'a pas pu extraire les docstrings de mon projet car il n'a pas trouvé mon module de projet.
J'ai résolu cela en ajoutant 2 chemins relatifs dans le fichier docs / conf.py:
sys.path.insert(0, os.path.abspath("."))
sys.path.insert(0, os.path.abspath("../"))
Alors que maintenant, le haut de la documentation / conf.py se présente comme suit:
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")