falha de construção do sphinx - autodoc não consegue importar / localizar módulo

104

Estou tentando começar com o Sphinx e pareço ter problemas implacáveis.

Comando: docs/sphinx-quickstart

Eu respondo todas as perguntas e tudo funciona bem.

Comando: docs/ls

Tudo parece normal. Resultado:build Makefile source

Comando: sphinx-build -d build/doctrees source build/html

Parece que funciona. Consegui abrir o arquivo index.html e ver uma "casca" do que estou querendo.

Quando tento colocar meu código-fonte real como a sourcepasta, tenho problemas.

Comando: sphinx-build -d build/doctrees ../ys_utils build/html

Resultado:

Making output directory...
Running Sphinx v1.1.3
loading pickled environment... not yet created
No builder selected, using default: html
loading intersphinx inventory from http://docs.python.org/objects.inv...
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
Traceback (most recent call last):                                                                                               
  File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.1.3-py2.6.egg/sphinx/ext/autodoc.py", line 321, in import_object
    __import__(self.modname)
ImportError: No module named ys_utils
Traceback (most recent call last):
  File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.1.3-py2.6.egg/sphinx/ext/autodoc.py", line 321, in import_object
    __import__(self.modname)
ImportError: No module named ys_utils.test_validate_ut
Traceback (most recent call last):
  File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.1.3-py2.6.egg/sphinx/ext/autodoc.py", line 321, in import_object
    __import__(self.modname)
ImportError: No module named ys_utils.git_utils
Traceback (most recent call last):
  File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.1.3-py2.6.egg/sphinx/ext/autodoc.py", line 321, in import_object
    __import__(self.modname)
ImportError: No module named setup.setup

/home/ricomoss/workspace/nextgen/ys_utils/ys_utils.rst:4: WARNING: autodoc can't import/find module 'ys_utils', it reported error: "No module named ys_utils", please check your spelling and sys.path
/home/ricomoss/workspace/nextgen/ys_utils/ys_utils.rst:10: WARNING: autodoc can't import/find module 'ys_utils.test_validate_ut', it reported error: "No module named ys_utils.test_validate_ut", please check your spelling and sys.path
/home/ricomoss/workspace/nextgen/ys_utils/ys_utils.rst:12: WARNING: don't know which module to import for autodocumenting u'UnitTests' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
/home/ricomoss/workspace/nextgen/ys_utils/ys_utils.rst:18: WARNING: autodoc can't import/find module 'ys_utils.git_utils', it reported error: "No module named ys_utils.git_utils", please check your spelling and sys.path
/home/ricomoss/workspace/nextgen/ys_utils/ys_utils.rst:24: WARNING: autodoc can't import/find module 'setup.setup', it reported error: "No module named setup.setup", please check your spelling and sys.path
WARNING: master file /home/ricomoss/workspace/nextgen/ys_utils/index.rst not found
looking for now-outdated files... none found
pickling environment... done
checking consistency... /home/ricomoss/workspace/nextgen/ys_utils/ys_utils.rst:: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [ 50%] index                                                                                                   
Exception occurred:
  File "/usr/local/lib/python2.6/dist-packages/Sphinx-1.1.3-py2.6.egg/sphinx/environment.py", line 1213, in get_doctree
    f = open(doctree_filename, 'rb')
IOError: [Errno 2] No such file or directory: '/home/ricomoss/workspace/nextgen/docs/build/doctrees/index.doctree'
The full traceback has been saved in /tmp/sphinx-err-jjJ7gM.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
Either send bugs to the mailing list at <http://groups.google.com/group/sphinx-dev/>,
or report them in the tracker at <http://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!

Sou um novato completo no Sphinx e relativamente novo nesse tipo de documentação. Alguém pode dar algumas sugestões?

Editar:

Eu gostaria de poder usar um Makefile para lidar com isso. No momento, tenho duas pastas em meu projeto.

nextgen/ls

docs ys_utils

Preciso nextgen/docs/Makefilegerar o HTML para ys_utilse todos os outros módulos que terei.

python python-sphinx autodoc Rico
fonte

Respostas:

87

Autodoc não consegue encontrar seus módulos, porque eles não estão em sys.path.

Você deve incluir o caminho para seus módulos no sys.pathem seu conf.py. Olhe no topo do seu conf.py(logo após a importação de sys), há uma sys.path.insert()declaração, que você pode adaptar.

A propósito: você pode usar o Makefilecriado pelo Sphinx para criar sua documentação. Apenas ligue

make

para ver as opções.

Se algo deu errado antes de tentar:

make clean

antes de correr make html.

bmu
fonte
59

Parece que os.path.append()está funcionando bem para o pessoal, mas se você seguir o conf.pymodelo, deverá inserir o caminho do módulo na frente do sys.pathuso os.path.insert(0, ...)e apenas adicionar um.

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

Se você configurou seu sphinxprojeto para usar diretórios builde separados source, essa chamada deve ser:

sys.path.insert(0, os.path.abspath('../..'))
Ryanjdillon
fonte
32

no conf.py

basta adicionar o caminho para a pasta do projeto.

sys.path.append('/home/workspace/myproj/myproj')
Pravitha V
fonte
8
A codificação permanente do caminho não é a melhor coisa que você pode fazer com o seu conf.py.
firegurafiku
18
Se você tem uma estrutura de projeto como /app, /docs... você pode usar sys.path.append(os.path.join(os.path.dirname(__name__), '..'))e depois usar .. automodule:: appem sua .rst-file.
fnkr
3

E se

  1. o caminho da raiz do módulo está definido corretamente em conf.py
  2. __init__.py está colocado corretamente
  3. primeira sintaxe está correta

e seu autodoc ainda não consegue encontrar os módulos ...

Pode ser porque as dependências desses módulos não são satisfeitas em seu ambiente python. Você vai querer verificar se todas as instruções de importação estão funcionando dentro dos módulos.

Ingako
fonte
4
Eu não entendo porque o sphinx precisa de dependências, é por causa da possibilidade de ter testes dentro do docstrings? Isso pode ser evitado (não preciso de nenhum pacote, só quero que o sphinx analise docstring para html).
cglacet
Se você não quiser importar essas dependências, use autodoc_mock_imports em seu arquivo conf.py
filip stepniak
1

Acho que fiz isso na primeira vez que tentei adicionar um arquivo à árvore toc. Acho que foi porque deixei de fora a linha em branco entre a linha: maxdepth e o nome do arquivo.

.. Animatrix Concepts documentation master file, created by
   sphinx-quickstart on Thu Mar 22 18:06:15 2012.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to Animatrix Concepts documentation!
============================================

Contents:

.. toctree::
   :maxdepth: 2

   stuff


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Acima está meu arquivo index.rst. stuff.rst reside no mesmo diretório que ele.

John Gaines Jr.
fonte
2
Para onde isso iria? Eu tenho index.rstem /docs/sourcee /ys_utils. Eu estou supondo que isso deveria estar na docsversão? Estou apenas usando o index.rstarquivo padrão que foi criado com sphinx-quickstart.
Rico
-1 a partir do traceback parece claro que os módulos não estão sys.path, então o autodoc não consegue encontrá-los. Os .rstarquivos foram encontrados.
bmu
1

Recebi o mesmo erro, mas foi causado por um motivo completamente diferente do explicado nas outras respostas.

Minha .. automethod:: mymodule.funcdiretiva deveria realmente ter sido:

.. automethod:: mymodule::func`
zimbro-
fonte
0

Você pode usar Pweave e noweb formatação para gerar documentos primeiros que incluem a saída do código embutido neles. Basicamente, você escreve seu primeiro arquivo, com o código Python embutido em blocos marcados como este:

<<echo=False>>=
print("some text that will appear in the rst file")
@

e Pweave irá executar esses pedaços e substituí-los por sua saída em um primeiro arquivo resultante, que você pode usar com o sphinx. Veja o exemplo de reST do Pweave para mais detalhes de sua aparência.

naught101
fonte