sphinx-build fail - autodoc không thể nhập / tìm mô-đun

Tôi đang cố gắng bắt đầu với Sphinx và dường như gặp phải những vấn đề không ngừng.

Chỉ huy: docs/sphinx-quickstart

Tôi trả lời tất cả các câu hỏi và mọi thứ hoạt động tốt.

Chỉ huy: docs/ls

Mọi thứ trông bình thường. Kết quả:build Makefile source

Chỉ huy: sphinx-build -d build/doctrees source build/html

Nó dường như hoạt động. Tôi đã có thể mở tệp index.html và thấy "vỏ" của những gì tôi muốn.

Khi tôi thử và đặt mã nguồn thực của mình làm sourcethư mục, tôi gặp sự cố.

Chỉ huy: sphinx-build -d build/doctrees ../ys_utils build/html

Kết quả:

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!

Tôi là một người mới hoàn thành với Sphinx và tương đối mới với loại tài liệu này. Bất cứ ai có thể cung cấp một số gợi ý?

Biên tập:

Tôi muốn có thể sử dụng Makefile để xử lý việc này. Hiện tại, tôi có hai thư mục trong dự án của mình.

nextgen/ls

docs ys_utils

Tôi cần nextgen/docs/Makefiletạo HTML cho ys_utilsvà tất cả các mô-đun khác mà tôi sẽ có.

Autodoc không thể tìm thấy các mô-đun của bạn, vì chúng không ở trong sys.path.

Bạn phải bao gồm đường dẫn đến các mô-đun sys.pathcủa bạn trong của bạn conf.py. Nhìn vào đầu trang của bạn conf.py(ngay sau khi nhập sys), có một sys.path.insert()câu lệnh mà bạn có thể điều chỉnh.

Nhân tiện: bạn có thể sử dụng Makefiledo Sphinx tạo ra để tạo tài liệu của mình. Chỉ cần gọi

make

để xem các tùy chọn.

Nếu có vấn đề gì xảy ra trước khi thử:

make clean

trước khi chạy make html.

Nghe có vẻ như os.path.append()đang hoạt động tốt đối với mọi người, nhưng nếu bạn làm theo conf.pymẫu, bạn sẽ chèn đường dẫn mô-đun vào phía trước của sys.pathviệc sử dụng os.path.insert(0, ...)và chỉ cần thêm một.

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

Nếu bạn đã thiết lập sphinxdự án của mình để sử dụng các thư mục buildvà sourcethư mục riêng biệt , cuộc gọi đó thay vào đó phải là:

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

trong conf.py

chỉ cần thêm đường dẫn đến thư mục dự án của bạn.

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

Nếu

1. đường dẫn gốc mô-đun được đặt chính xác trong conf.py
2. __init__.py được đặt chính xác
3. cú pháp đầu tiên là đúng

và autodoc của bạn vẫn không thể tìm thấy các mô-đun ...

Có thể là do các phần phụ thuộc của các mô-đun đó không được thỏa mãn trong môi trường python của bạn. Bạn sẽ muốn kiểm tra xem tất cả các câu lệnh nhập có hoạt động trong các mô-đun hay không.

Tôi nghĩ rằng tôi đã làm điều này lần đầu tiên tôi cố gắng thêm một tệp vào toctree. Tôi nghĩ đó là do tôi đã bỏ trống dòng giữa dòng: maxdepth và tên tệp.

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

Trên đây là tệp index.rst của tôi. thứ.rst nằm trong cùng thư mục với nó.

Tôi cũng gặp lỗi này nhưng do một lý do hoàn toàn khác với lý do được giải thích trong các câu trả lời khác.

.. automethod:: mymodule.funcChỉ thị của tôi thực sự nên là:

.. automethod:: mymodule::func`

Bạn có thể sử dụng định dạng Pweave và noweb để tạo tài liệu đầu tiên bao gồm đầu ra của mã được nhúng trong chúng. Về cơ bản, bạn viết tệp đầu tiên của mình, với mã python được nhúng trong các đoạn được đánh dấu như sau:

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

và Pweave sẽ thực thi các phần đó và thay thế chúng bằng đầu ra của chúng trong một tệp đầu tiên kết quả, sau đó bạn có thể sử dụng với sphinx. Xem ví dụ về Pweave reST để biết thêm chi tiết về giao diện của nó.