Readthedocs.org: `pip install--no-deps`がSphinxautodocの依存関係を満たすことを許可する

作成日 2019年03月20日 · 3コメント · ソース: readthedocs/readthedocs.org

詳細

ドキュメントプロジェクトのURLを読む： https ：
ビルドURL（該当する場合）： https ：
ドキュメントのユーザー名を読む（該当する場合）：zhuangjw

問題

Sphinx-autodocを使用してPythonパッケージのAPIドキュメントを生成し

もともと私はCondaを使用してreadthedocsへの完全な依存関係をインストールしましたが、ビルドに時間がかかりすぎ、場合によっては失敗することさえありました（＃4695）。そこで、純粋なpip （https://github.com/JiaweiZhuang/xESMF/commit/53816d397b3c8f27b195132b27dbb41847e34e0f）に切り替えました。これにより、ビルドが大幅に加速されました。ただし、その切り替え以降、Sphinx-autodocはAPIドキュメントの生成に失敗しました。私のAPIページはほとんど空白です：

Screen Shot 2019-03-20 at 2 51 31 PM

これは、私のパッケージ自体に、 pipインストールできない大きな依存関係があるためです。一部のC / Fortran拡張機能は、 condaインストールする必要があります。したがって、autodocは私のパッケージをインポートできません：

WARNING: autodoc: failed to import module 'xesmf.frontend'; the following exception was raised:
No module named 'xesmf'
WARNING: autodoc: failed to import module 'xesmf.backend'; the following exception was raised:
No module named 'xesmf'
...

私が試した方法

2つのハックを使用して、

pip install --no-deps xesmfパッケージのインストールを強制します。
conf.py autodoc_mock_imports = ['numpy', 'xarray', 'scipy', 'ESMF']を追加して、依存関係をモックインポートします。その中でも、 ESMFは非常に重い依存関係であり、

autodoc_mock_importsを使用しても、パッケージxesmfをpip-installして、sphinx-autodocのdocstringを提供する必要があります。 Read the Docs Configuration Fileを読みましたが、 --no-depsオプションを指定したり、カスタムpipコマンドを追加したりする方法が見つかりません。

今のところ、APIドキュメントをオンラインで正しく構築するための2つの非常に満足のいくソリューションしか考えられません。

condaアプローチに戻って、完全な依存関係をインストールします。ドキュメントのビルドにはパッケージ内のdocstringのみが必要であり、C / Fortran拡張機能は必要ないため、これは非常にやり過ぎです。
または、パッケージのsetup.pyの要件を変更して、 --no-depsオプションなしでpip-installできるようにします。これは私のパッケージ自体には良くありません。

だから私はまだより良い解決策を探しています。任意の提案をいただければ幸いです！

追加情報

ラップトップで正しいドキュメントを作成するための完全な手順は次のとおりです。

conda create -n doc python=3.6
conda activate doc
conda install -c conda-forge pandoc
pip install numpydoc ipython nbsphinx sphinx_rtd_theme
pip install --no-deps xesmf
git clone https://github.com/JiaweiZhuang/xesmf
cd xesmf/doc
make html

正しいAPIページは次のようになります。
Screen Shot 2019-03-20 at 3 23 15 PM

Support

ソース

JiaweiZhuang

👍3

最も参考になるコメント

@stsewd提案をありがとう！ setup.pyを微調整して、次のようにしました。

on_rtd = os.environ.get('READTHEDOCS') == 'True'
if on_rtd:
    INSTALL_REQUIRES = []
else:
    INSTALL_REQUIRES = ['esmpy', 'xarray', 'numpy', 'scipy']

（https://github.com/JiaweiZhuang/xESMF/commit/5ce3364bfbd3081aad848c5cf4ac54a287ca236e）

少しハッキーな感じがしますが、問題は解決します。再度、感謝します。

JiaweiZhuang 2019年03月21日

👍3 ❤2

全てのコメント3件

申し訳ありませんが、pipのオプションをこれ以上追加するつもりはないと思います。私の頭に浮かぶ解決策の1つは、 READTHEDOCS env変数https://docs.readthedocs.io/en/stable/faq.html#how-do-i-change-behavior-for-を利用することです

stsewd 2019年03月20日

また、依存関係が必要な場合は、ドキュメント専用のカスタム要件ファイルを作成できます。