Python Sphinxautodocがreadthedocsでレンダリングされない

Dec 29 2020

Githubでspike2pyというPythonパッケージをホストしています。Sphinxファイルと.rstファイルを使用してドキュメントを準備しました。これらのファイルは、ここのGitHubでホストされています。make htmlローカルで正常に実行し、目的の出力を取得できます。つまり、ドキュメントのリファレンスガイドの部分には、コードに含めたdocstringを使用して自動的に生成され、autoclassand autofunction(reference_guide.rst)の呼び出しを使用して参照されるAPIが含まれています。

たとえば、リファレンスガイドをローカルでレンダリングすると、リファレンスガイドの最初の部分は次のようになります。

ただし、ドキュメントが表示される場合readthedocs(ここを参照)、リファレンスガイドには抽出されたドキュメントが含まれていません。.rstファイルにあるヘッダーのみ。

期待される動作

readthedocsでレンダリングされたドキュメントは、ローカルでレンダリングされたものと同じであると期待していました。ただし、これは発生していません。

ここを見て、現在のバージョンのドキュメントのreadthedocsに表示されているバージョンを確認しました。

しかし、PDFまたはHTMLバージョンのドキュメントをダウンロードしようとすると、リファレンスガイドにdocstringが含まれていません。

他の情報

readthedocsのドキュメントによると、ローカルビルドはGitHubにプッシュしないでください。ソースファイルのみ。

これはこの問題にいくらか関連していますが、提案されたソリューションを機能させることができませんでした。

更新私はスティーブピアシーによって推奨された解決策に従いました、そしてこれは問題の一部を解決しました。docs/requirements.txtファイルだけでなくファイルも追加しました.readthedocs.yml

次に、ビルドがPython3.7.9を使用していることに気付きました。Python> = 3.8の型ヒントを使用していたことを考えると、.readthedocs.ymlファイルでPythonのバージョンを指定する必要がありました。

それから私はRTDビルドで立ち往生し、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

しかし、私はそれから私ので以下を指定することによってこれを解決しました.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は、プロジェクトモジュールが見つからなかったため、プロジェクトからdocstringを抽出できませんでした。

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