Readthedocs.org: Permitir que `pip install --no-deps` atenda às dependências do Sphinx autodoc

Criado em 20 mar. 2019 · 3Comentários · Fonte: readthedocs/readthedocs.org

Detalhes

Leia o URL do projeto Docs: https://readthedocs.org/projects/xesmf
URL de compilação (se aplicável): https://readthedocs.org/projects/xesmf/builds/8484627/
Leia o nome de usuário do Documentos (se aplicável): zhuangjw

Problema

Estou usando o Sphinx-autodoc para gerar documentos de API para meu pacote Python .

Originalmente, usei o Conda para instalar as dependências completas em readthedocs, mas demorou muito para construir e às vezes até falhou (# 4695). Então, mudei para pip puro (https://github.com/JiaweiZhuang/xESMF/commit/53816d397b3c8f27b195132b27dbb41847e34e0f), que acelerou muito a compilação. No entanto, desde essa mudança, Sphinx-autodoc falhou ao gerar documentos de API. Minha página da API está quase em branco:

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

Isso ocorre porque meu próprio pacote tem dependências pesadas que não podem ser instaladas por pip . Algumas extensões C / Fortran devem ser instaladas por conda . Portanto, o autodoc não pode importar meu pacote:

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

Métodos que tentei

Sou capaz de gerar documentos API corretos com pip localmente , usando dois hacks:

Force a instalação do meu pacote em pip install --no-deps xesmf .
Importe simulações das dependências adicionando autodoc_mock_imports = ['numpy', 'xarray', 'scipy', 'ESMF'] em conf.py . Entre eles, o ESMF é uma dependência extremamente pesada que só pode ser instalada pelo Conda (e leva muito tempo para instalar).

Mesmo com autodoc_mock_imports , ainda tenho que instalar meu pacote xesmf com pip para fornecer a docstring para sphinx-autodoc. Eu li o arquivo de configuração Read the Docs, mas não consigo encontrar uma maneira de especificar a opção --no-deps ou adicionar comandos pip personalizados.

No momento, só consigo pensar em duas soluções altamente insatisfatórias para criar os documentos de API corretamente online:

Reverta para a abordagem conda para instalar as dependências completas. Este é um grande exagero porque construir os docs só precisa dos docstrings do meu pacote, não daquelas extensões C / Fortran.
ou, altere o requisito no setup.py meu pacote, para que eu possa instalá-lo com pip sem a opção --no-deps . Isso não é bom para o meu pacote em si.

Portanto, ainda estou procurando uma solução melhor. Qualquer sugestão seria apreciada!

Informação extra

Aqui estão as etapas completas para criar o documento correto em meu laptop:

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

A página correta da API seria assim:
Screen Shot 2019-03-20 at 3 23 15 PM

Support

Fonte

JiaweiZhuang

👍3

Comentários muito úteis

@stsewd Obrigado pela sugestão! Ajustei setup.py para que:

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)

Parece um pouco maluco, mas resolve o problema. Obrigado novamente.

JiaweiZhuang em 21 mar. 2019

👍3 ❤2

Todos 3 comentários

Não acho que vamos adicionar mais opções para pip, desculpe. Uma solução que me vem à mente é usar a variável READTHEDOCS env https://docs.readthedocs.io/en/stable/faq.html#how -do-i-change-behavior-for- leia os documentos em seu arquivo setup.py.

stsewd em 20 mar. 2019

E se você precisar de algumas dependências, pode apenas criar um arquivo de requisitos personalizados apenas para seus documentos.