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

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.

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.

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('../..'))

no conf.py

basta adicionar o caminho para a pasta do projeto.

sys.path.append('/home/workspace/myproj/myproj')

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.

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.

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`

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.