Python Sphinx autodoc não renderiza em readthedocs

Dec 29 2020

Eu tenho um pacote Python hospedado no Github chamado spike2py . Preparei meus documentos usando os arquivos Sphinx e .rst. Esses arquivos estão hospedados no GitHub aqui . Consigo executar make htmllocalmente com êxito e obter a saída desejada. Ou seja, a parte do Guia de referência da documentação contém a API gerada automaticamente usando a docstring que incluí em meu código e referenciada usando chamadas para autoclasse autofunction( reference_guide.rst ).

Por exemplo, aqui está a aparência da primeira parte do Guia de referência quando eu o renderizo localmente:

No entanto, quando a documentação é processada readthedocs( veja aqui ), o Guia de Referência não contém as doutrinas extraídas; apenas os cabeçalhos encontrados no arquivo .rst.

Comportamento esperado

Eu esperava que os documentos renderizados no readthedocs fossem iguais aos renderizados localmente. No entanto, isso não está acontecendo.

Olhando aqui , confirmei que a versão apresentada no readthedocs na versão atual da minha documentação.

Mas quando tento baixar versões em PDF ou HTML da documentação, o Guia de Referência não inclui as docstrings.

Outras informações

De acordo com a documentação do readthedocs , as compilações locais não devem ser enviadas ao GitHub; apenas os arquivos de origem.

Isso está um tanto relacionado a esse problema , mas não consegui fazer a solução proposta funcionar.

ATUALIZAÇÃO Segui a solução recomendada por Steve Piercy e isso resolveu parte do problema. Eu adicionei um docs/requirements.txtarquivo, bem como um .readthedocs.ymlarquivo.

Em seguida, percebi que a construção estava usando Python 3.7.9. Visto que eu estava usando dicas de tipo do Python> = 3.8, tive que especificar a versão do Python no .readthedocs.ymlarquivo.

Então, eu estava preso com a compilação do RTD me dizendo que não conseguia encontrar meu arquivo 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

Mas resolvi isso especificando o seguinte em meu .readthedocs.yml:

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

Após essa correção, os documentos são criados com o que parece não haver erros e incluem o seguinte:

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 sim, as doutrinas apareceram no RTD.

Respostas

1 StevePiercy Dec 30 2020 at 17:08

As dependências do seu projeto não são especificadas no RTD, mas você instalou as dependências localmente. Você pode verificar isso no log de construção . Visite o Builds do seu projeto, clique em um build e clique em "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)

Para remediar a situação, você deve especificar que as dependências do seu projeto devem ser instaladas. Consulte Especificando Dependências .

Você deve:

  1. Crie um arquivo de requisitos de pip que especifica os requisitos , ou
  2. Crie um arquivo que especifica uma pip installopção que instalará os requisitos que já estão definidos em outro lugar, como em uma setup.py docs_requiresestrofe. Veja um exemplo no repositório Pyramid com seu 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},

Depois de definir os requisitos do projeto neste arquivo, você deve configurar o Read the Docs para reconhecer este arquivo para instalar dependências. O método preferido é usar um arquivo de configuração , mas você também pode fazer isso por meio do painel de administração do projeto .

SoleG Jan 01 2021 at 20:54

Eu tive exatamente o mesmo problema. Readthedocs não conseguiu extrair as docstrings do meu projeto porque não encontrou o módulo do meu projeto.

Resolvi isso adicionando 2 caminhos relativos no docs / conf.py:

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

Para que agora a parte superior do docs / conf.py tenha a seguinte aparência:

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