Readthedocs.org: `pip install --no-deps`가 Sphinx autodoc에 대한 종속성을 충족하도록 허용

세부

• 문서 프로젝트 URL 읽기: https://readthedocs.org/projects/xesmf
• 빌드 URL(해당되는 경우): https://readthedocs.org/projects/xesmf/builds/8484627/
• 문서 사용자 이름 읽기(해당되는 경우): zhuangjw

문제

내 Python 패키지에 대한 API 문서를 생성하기 위해 Sphinx-autodoc 을 사용하고 있습니다.

원래 readthedocs에 대한 전체 종속성을 설치하기 위해 Conda를 사용했지만 빌드하는 데 너무 오래 걸리고 때로는 실패하기도 했습니다(#4695). 그래서 순수 pip (https://github.com/JiaweiZhuang/xESMF/commit/53816d397b3c8f27b195132b27dbb41847e34e0f)로 전환하여 빌드 속도가 많이 빨라졌습니다. 그러나 그 스위치 이후로 Sphinx-autodoc은 API 문서를 생성하지 못했습니다. 내 API 페이지 가 거의 비어 있습니다.

내 패키지 자체에 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'
...

내가 시도한 방법

두 가지 해킹을 사용하여 로컬 에서 pip

• pip install --no-deps xesmf 내 패키지를 강제로 설치합니다.
• autodoc_mock_imports = ['numpy', 'xarray', 'scipy', 'ESMF'] 에 conf.py autodoc_mock_imports = ['numpy', 'xarray', 'scipy', 'ESMF'] 를 추가하여 종속성을 모의 가져옵니다 . 그 중 ESMF 는 높습니다 .

autodoc_mock_imports xesmf 를 사용하더라도 sphinx-autodoc에 대한 독스트링을 제공하려면 문서 구성 파일 읽기를 읽었지만 --no-deps 옵션을 지정하거나 사용자 정의 pip 명령을 추가하는 방법을 찾을 수 없습니다.

지금 당장은 API 문서를 온라인으로 올바르게 구축하기 위한 매우 불만족스러운 두 가지 솔루션만 생각할 수 있습니다.

• 전체 종속성을 설치하려면 conda 접근 방식으로 되돌립니다. 문서를 빌드하는 데 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 페이지는 다음과 같습니다.