sphinx-build ล้มเหลว - autodoc ไม่สามารถนำเข้า / ค้นหาโมดูล

ฉันกำลังพยายามเริ่มต้นกับ 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 เพื่อจัดการสิ่งนี้ ณ ตอนนี้ฉันมีสองโฟลเดอร์ในโครงการของฉัน

nextgen/ls

docs ys_utils

ฉันต้องการnextgen/docs/Makefileสร้าง HTML สำหรับys_utilsและโมดูลอื่น ๆ ทั้งหมดที่ฉันจะมี

Autodoc ไม่พบโมดูลของคุณเนื่องจากไม่ได้อยู่ในsys.pathไฟล์.

คุณจะต้องรวมถึงเส้นทางไปยังโมดูลของคุณในในในของคุณsys.path conf.pyดูที่ด้านบนของคุณconf.py(หลังการนำเข้าsys) มีsys.path.insert()คำสั่งที่คุณสามารถปรับเปลี่ยนได้

โดยวิธีการ: คุณสามารถใช้Makefileสฟิงซ์ที่สร้างขึ้นเพื่อสร้างเอกสารของคุณ เพียงโทร

make

เพื่อดูตัวเลือก

หากเกิดข้อผิดพลาดก่อนลอง:

make clean

make htmlก่อนที่จะใช้

ดูเหมือนว่าos.path.append()จะใช้งานได้ดีสำหรับคนทั่วไป แต่ถ้าคุณทำตามconf.pyเทมเพลตคุณจะต้องแทรกเส้นทางโมดูลที่ด้านหน้าของการsys.pathใช้os.path.insert(0, ...)งานและเพิ่มส่วนเสริม.

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

หากคุณตั้งค่าsphinxโปรเจ็กต์ของคุณเพื่อใช้แยกbuildและsourceไดเร็กทอรีการโทรนั้นควรเป็น:

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

ใน conf.py

เพียงแค่เพิ่มเส้นทางไปยังโฟลเดอร์โครงการของคุณ

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

ถ้า

1. เส้นทางรูทโมดูลถูกตั้งค่าอย่างถูกต้องใน conf.py
2. __init__.py วางอย่างถูกต้อง
3. ไวยากรณ์ rst ถูกต้อง

และ autodoc ของคุณยังไม่พบโมดูล ...

อาจเป็นเพราะการอ้างอิงของโมดูลเหล่านั้นไม่เป็นที่พอใจภายใต้สภาพแวดล้อม python ของคุณ คุณจะต้องตรวจสอบว่าคำสั่งการนำเข้าทั้งหมดทำงานภายในโมดูลหรือไม่

ฉันคิดว่าฉันทำสิ่งนี้ในครั้งแรกที่พยายามเพิ่มไฟล์ลงใน 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 อยู่ในไดเร็กทอรีเดียวกับมัน

ฉันได้รับข้อผิดพลาดเดียวกันนี้ แต่เกิดจากสาเหตุที่แตกต่างไปจากที่อธิบายไว้ในคำตอบอื่น ๆ

.. automethod:: mymodule.funcคำสั่งของฉันควรเป็น:

.. automethod:: mymodule::func`

คุณสามารถใช้Pweaveและ noweb การจัดรูปแบบในการสร้างเอกสารแรกที่มีการส่งออกของรหัสที่ฝังตัวอยู่ในพวกเขา โดยทั่วไปคุณจะเขียนไฟล์ rst ของคุณโดยมีโค้ด python ฝังอยู่ในส่วนที่ทำเครื่องหมายไว้ดังนี้:

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

และ Pweave จะดำเนินการชิ้นส่วนเหล่านั้นและแทนที่ด้วยเอาต์พุตในไฟล์ rst ที่เป็นผลลัพธ์ซึ่งคุณสามารถใช้กับสฟิงซ์ได้ ดูตัวอย่าง Pweave reSTสำหรับรายละเอียดเพิ่มเติมว่าหน้าตาเป็นอย่างไร