readthedocs에서 Python Sphinx autodoc이 렌더링되지 않음

Dec 29 2020

Github에 spike2py 라는 Python 패키지가 있습니다. Sphinx 및 .rst 파일을 사용하여 문서를 준비했습니다. 이러한 파일은 여기 GitHub 에서 호스팅 됩니다 . make html로컬 에서 성공적으로 실행 하고 원하는 출력을 얻을 수 있습니다. 즉, 문서의 참조 가이드 부분에는 코드에 포함 된 독 스트링을 사용하여 자동으로 생성되고 autoclassand autofunction( reference_guide.rst )에 대한 호출을 사용하여 참조한 API가 포함되어 있습니다.

예를 들어, 다음은 참조 가이드의 첫 번째 부분을 로컬로 렌더링했을 때의 모습입니다.

그러나 문서가 렌더링 될 때 readthedocs( 여기 참조 ) 참조 안내서에는 추출 된 문서가 포함되지 않습니다. .rst 파일에있는 헤더 만.

예상되는 행동

readthedocs에서 렌더링 된 문서가 로컬로 렌더링 된 문서와 동일 할 것으로 예상했습니다. 그러나 이것은 일어나지 않습니다.

보면 여기에 , 나는 버전은 내 문서의 현재 버전에서 readthedocs에 표시되고 있음을 확인했다.

그러나 문서의 PDF 또는 HTML 버전을 다운로드하려고하면 참조 안내서에 독 스트링이 포함되어 있지 않습니다.

기타 정보

readthedocs 문서 에 따르면 로컬 빌드를 GitHub에 푸시하면 안됩니다. 소스 파일 만.

이것은 이 문제 와 다소 관련 이 있지만 제안 된 솔루션을 작동시킬 수 없었습니다.

업데이트 나는 Steve Piercy가 추천 한 해결책을 따랐고 이것은 문제의 일부를 해결했습니다. docs/requirements.txt파일과 파일을 추가했습니다 .readthedocs.yml.

다음으로 빌드가 Python 3.7.9를 사용하고 있음을 알았습니다. Python> = 3.8에서 유형 힌트를 사용하고 있다는 점을 감안할 때 .readthedocs.yml파일 에 Python 버전을 지정해야했습니다 .

그런 다음 내 index.rst 파일을 찾을 수 없다는 RTD 빌드에 갇혔습니다.

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

하지만 다음을 지정하여이 문제를 해결했습니다 .readthedocs.yml.

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

이 수정 후 문서는 오류가없는 것으로 표시되며 다음을 포함합니다.

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

그리고 네, 문서는 RTD에 나타났습니다.

답변

1 StevePiercy Dec 30 2020 at 17:08

프로젝트의 종속성이 RTD에 지정되지 않았지만 로컬에 종속성을 설치했습니다. 빌드 로그 에서이를 확인할 수 있습니다 . 프로젝트의 빌드를 방문하여 빌드를 클릭 한 다음 "원시보기"를 클릭하십시오.

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)

상황을 해결하려면 프로젝트의 종속성을 설치해야 함을 지정해야합니다. 종속성 지정을 참조하십시오 .

다음 중 하나를 수행해야합니다.

  1. 요구 사항을 지정 하는 pip 요구 사항 파일을 만듭니다. 또는
  2. 스탠자 pip install에서와 같이 이미 다른 곳에 정의 된 요구 사항을 설치 하는 옵션 을 지정하는 파일을 작성하십시오 setup.py docs_requires. rtd.txt 및 setup.py 가있는 Pyramid 저장소의 예를 참조하세요 .

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},

이 파일에서 프로젝트 요구 사항을 정의한 다음, 종속성을 설치하기 위해이 파일을 인식하도록 문서 읽기를 구성해야합니다. 선호하는 방법은 구성 파일 을 사용하는 것이지만 프로젝트의 관리 대시 보드를 통해서도이 작업을 수행 할 수 있습니다 .

SoleG Jan 01 2021 at 20:54

나는 똑같은 문제가 있었다. Readthedocs는 내 프로젝트 모듈을 찾지 못했기 때문에 내 프로젝트에서 독 스트링을 추출 할 수 없습니다.

docs / conf.py에 2 개의 상대 경로를 추가하여이 문제를 해결했습니다.

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

이제 docs / conf.py의 상단은 다음과 같습니다.

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