Readthedocs.org: Izinkan `pip install --no-deps` untuk memenuhi dependensi untuk Sphinx autodoc

Dibuat pada 20 Mar 2019 · 3Komentar · Sumber: readthedocs/readthedocs.org

rincian

Baca URL proyek Dokumen: https://readthedocs.org/projects/xesmf
Membangun URL (jika berlaku): https://readthedocs.org/projects/xesmf/builds/8484627/
Baca nama pengguna Documents (jika ada): zhuangjw

Masalah

Saya menggunakan Sphinx-autodoc untuk menghasilkan dokumen API untuk paket Python saya .

Awalnya saya menggunakan Conda untuk menginstal dependensi penuh pada readthedocs, tetapi butuh waktu terlalu lama untuk membangun dan kadang-kadang bahkan gagal (#4695). Jadi, saya beralih ke pip murni (https://github.com/JiaweiZhuang/xESMF/commit/53816d397b3c8f27b195132b27dbb41847e34e0f), yang banyak mempercepat pembangunan. Namun, sejak peralihan itu, Sphinx-autodoc gagal menghasilkan dokumen API. Halaman API saya hampir kosong:

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

Ini karena paket saya sendiri memiliki dependensi berat yang tidak dapat diinstal oleh pip . Beberapa ekstensi C/Fortran harus diinstal oleh conda . Jadi, autodoc tidak dapat mengimpor paket saya:

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'
...

Metode yang telah saya coba

Saya dapat membuat dokumen API yang benar dengan pip secara lokal , menggunakan dua peretasan:

Paksa instalasi paket saya dengan pip install --no-deps xesmf .
Mock-import dependensi dengan menambahkan autodoc_mock_imports = ['numpy', 'xarray', 'scipy', 'ESMF'] di conf.py . Di antara mereka, ESMF adalah ketergantungan yang sangat berat yang hanya dapat diinstal oleh Conda (dan membutuhkan waktu lama untuk menginstal).

Bahkan dengan autodoc_mock_imports , saya masih harus menginstal pip paket saya xesmf untuk menyediakan docstring untuk sphinx-autodoc. Saya telah membaca Baca File Konfigurasi Dokumen tetapi tidak dapat menemukan cara untuk menentukan opsi --no-deps atau menambahkan perintah pip khusus.

Saat ini, saya hanya dapat memikirkan dua solusi yang sangat tidak memuaskan untuk membuat dokumen API secara online dengan benar:

Kembali ke pendekatan conda untuk menginstal dependensi penuh. Ini adalah pekerjaan yang berlebihan karena membangun dokumen hanya membutuhkan dokumen dalam paket saya, bukan ekstensi C/Fortran itu.
atau, ubah persyaratan dalam paket saya setup.py , jadi saya dapat menginstal pip tanpa opsi --no-deps . Ini tidak baik untuk paket saya sendiri.

Jadi saya masih mencari solusi yang lebih baik. Setiap saran akan dihargai!

Informasi tambahan

Berikut adalah langkah-langkah lengkap untuk membuat dokumen yang benar di laptop saya:

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

Halaman API yang benar akan terlihat seperti:
Screen Shot 2019-03-20 at 3 23 15 PM

Support

Sumber

JiaweiZhuang

👍3

Komentar yang paling membantu

@stsewd Terima kasih atas sarannya! Saya mengubah setup.py sehingga:

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)

Terasa sedikit hacky tetapi memecahkan masalah. Terima kasih lagi.

JiaweiZhuang pada 21 Mar 2019

👍3 ❤2

Semua 3 komentar

Saya tidak berpikir kami akan menambahkan lebih banyak opsi untuk pip, maaf. Salah satu solusi yang muncul di benak saya adalah menggunakan variabel env READTHEDOCS https://docs.readthedocs.io/en/stable/faq.html#how -do-i-change-behavior-for- read-the-docs di file setup.py Anda.

stsewd pada 20 Mar 2019

Dan jika Anda memerlukan beberapa dependensi, Anda bisa membuat file persyaratan khusus hanya untuk dokumen Anda.