readthedocs에서 Python Sphinx autodoc이 렌더링되지 않음
Github에 spike2py 라는 Python 패키지가 있습니다. Sphinx 및 .rst 파일을 사용하여 문서를 준비했습니다. 이러한 파일은 여기 GitHub 에서 호스팅 됩니다 . make html
로컬 에서 성공적으로 실행 하고 원하는 출력을 얻을 수 있습니다. 즉, 문서의 참조 가이드 부분에는 코드에 포함 된 독 스트링을 사용하여 자동으로 생성되고 autoclass
and 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에 나타났습니다.
답변
프로젝트의 종속성이 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)
상황을 해결하려면 프로젝트의 종속성을 설치해야 함을 지정해야합니다. 종속성 지정을 참조하십시오 .
다음 중 하나를 수행해야합니다.
- 요구 사항을 지정 하는 pip 요구 사항 파일을 만듭니다. 또는
- 스탠자
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},
이 파일에서 프로젝트 요구 사항을 정의한 다음, 종속성을 설치하기 위해이 파일을 인식하도록 문서 읽기를 구성해야합니다. 선호하는 방법은 구성 파일 을 사용하는 것이지만 프로젝트의 관리 대시 보드를 통해서도이 작업을 수행 할 수 있습니다 .
나는 똑같은 문제가 있었다. 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")