sphinx-buildが失敗する-autodocがモジュールをインポート/検索できない


104

私はSphinxを使い始めようとしていますが、容赦ない問題があるようです。

コマンド: docs/sphinx-quickstart

私はすべての質問に答え、すべてがうまくいきます。

コマンド: docs/ls

すべてが正常に見えます。結果:build Makefile source

コマンド: sphinx-build -d build/doctrees source build/html

動作するようです。index.htmlファイルを開いて、必要なものの「シェル」を表示することができました。

実際のソースコードをsourceフォルダーとして配置しようとすると、問題が発生します。

コマンド: sphinx-build -d build/doctrees ../ys_utils build/html

結果:

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!

私はSphinxの完全な初心者であり、この種のドキュメントは比較的新しいものです。誰かがいくつかの提案を提供できますか?

編集:

Makefileを使用してこれを処理できるようにしたいと思います。現在、プロジェクトには2つのフォルダがあります。

nextgen/ls

docs ys_utils

nextgen/docs/MakefileのHTMLとys_utils、これから作成する他のすべてのモジュールを生成する必要があります。

回答:


86

モジュールがにないため、Autodocはモジュールを見つけることができませんsys.path

モジュールのパスをのに含める必要がありsys.pathますconf.py。あなたの上部を見てくださいconf.py(のインポート直後sys)、sys.path.insert()適応できるステートメントがあります。

ちなみに、MakefileSphinxで作成したドキュメントを使用してドキュメントを作成できます。電話するだけ

make

オプションを表示します。

試す前に問題が発生した場合:

make clean

実行する前にmake html


59

それはのように聞こえるos.path.append()人々のために[OK]を働いているが、あなたが続く場合はconf.py、テンプレートを、あなたは目の前にモジュールパスを挿入するsys.path使用してos.path.insert(0, ...)、ちょうど余分を追加します.

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

sphinx個別のbuildsourceディレクトリを使用するようにプロジェクトを設定した場合、その呼び出しは次のようになります。

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

32

conf.py

プロジェクトフォルダへのパスを追加するだけです。

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

8
パスのハードコーディングは、で実行できる最善の方法ではありませんconf.py
firegurafiku 2015

18
あなたのようなプロジェクト構造を持っている場合は/app/docs、...あなたは、使用するかもしれないsys.path.append(os.path.join(os.path.dirname(__name__), '..'))し、次に使う.. automodule:: appあなたに.rst-file。
fnkr

3

もし

  1. モジュールのルートパスがconf.pyに正しく設定されている
  2. __init__.py 正しく配置されている
  3. 最初の構文は正しい

そしてあなたのautodocはまだモジュールを見つけることができません...

これらのモジュールの依存関係がpython環境で満たされていないことが原因である可能性があります。すべてのインポート文がモジュール内で機能しているかどうかを確認する必要があります。


4
sphinxが依存関係を必要とする理由がわかりません。これは、docstring内にテストがある可能性があるためですか?これを回避できますか(パッケージは必要ありません。sphinxでdocstringをhtmlに解析したいだけです)。
cglacet

:あなたはこれらの依存関係をインポートしたくない場合は、あなたのconf.pyファイルでautodoc_mock_importsを使用sphinx-doc.org/en/master/usage/extensions/...
フィリップstepniak

1

これを初めてtoctreeにファイルを追加しようとしたときに行ったと思います。:maxdepth行とファイル名の間の空白行を省略したためだと思います。

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

上記は私のindex.rstファイルです。stuff.rstはそれと同じディレクトリにあります。


2
これはどこに行くのでしょうか?私が持っているindex.rst/docs/sourceして/ys_utils。これはdocsバージョンにあるはずだと思いますか?index.rstで作成されたデフォルトのファイルを使用していますsphinx-quickstart
リコ

-1トレースバックから、モジュールがにないことが明らかであると思われるsys.pathため、autodocはそれらを検出しません。.rstファイルが発見されました。
bmu

1

これと同じエラーが発生しましたが、他の回答で説明されているものとは完全に異なる理由で発生しました。

私の.. automethod:: mymodule.funcディレクティブは実際には次のとおりでした:

.. automethod:: mymodule::func`

0

Pweaveおよびnowebフォーマットを使用して、埋め込まれたコードの出力を含む最初のドキュメントを生成できます。基本的には、次のようにマークされたチャンクにPythonコードを埋め込んで、最初のファイルを記述します。

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

そして、Pweaveはそれらのチャンクを実行し、それらを結果のrstファイルの出力に置き換えます。これは、sphinxで使用できます。外観の詳細については、Pweave reSTの例を参照してください。

弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.