sphinx-build gagal - modul autodoc tidak dapat mengimpor / menemukan

104

Saya mencoba untuk memulai dengan Sphinx dan sepertinya mengalami masalah tanpa henti.

Perintah: docs/sphinx-quickstart

Saya menjawab semua pertanyaan dan semuanya bekerja dengan baik.

Perintah: docs/ls

Semuanya terlihat normal. Hasil:build Makefile source

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

Sepertinya berhasil. Saya bisa membuka file index.html dan melihat "shell" dari apa yang saya inginkan.

Ketika saya mencoba dan meletakkan kode sumber saya yang sebenarnya sebagai sourcefolder, saya mengalami masalah.

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

Hasil:

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!

Saya benar-benar pemula di Sphinx dan relatif baru dalam jenis dokumentasi ini. Adakah yang bisa menawarkan beberapa saran?

Edit:

Saya ingin bisa menggunakan Makefile untuk menangani ini. Sampai sekarang saya memiliki dua folder dalam proyek saya.

nextgen/ls

docs ys_utils

Saya perlu nextgen/docs/Makefilemembuat HTML untuk ys_utilsdan semua modul lain yang akan saya miliki.

Rico
sumber

Jawaban:

87

Autodoc tidak dapat menemukan modul Anda, karena tidak ada di dalamnya sys.path.

Anda harus menyertakan path ke modul Anda di dalam sys.pathdi Anda conf.py. Lihat di bagian atas Anda conf.py(setelah impor sys), ada sys.path.insert()pernyataan, yang dapat Anda adaptasi.

Ngomong-ngomong: Anda dapat menggunakan file yang Makefiledibuat oleh Sphinx untuk membuat dokumentasi Anda. Telepon saja

make

untuk melihat opsi.

Jika ada yang tidak beres sebelum mencoba:

make clean

sebelum berlari make html.

bmu
sumber
59

Sepertinya os.path.append()berfungsi dengan baik untuk orang-orang, tetapi jika Anda mengikuti conf.pytemplatnya, Anda akan memasukkan jalur modul ke depan sys.pathpenggunaan os.path.insert(0, ...), dan hanya menambahkan tambahan.

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

Jika Anda telah menyiapkan sphinxproyek Anda untuk menggunakan direktori builddan terpisah source, panggilan itu seharusnya:

sys.path.insert(0, os.path.abspath('../..'))
ryanjdillon.dll
sumber
32

di conf.py

cukup tambahkan jalur ke folder proyek Anda.

sys.path.append('/home/workspace/myproj/myproj')
Pravitha V
sumber
8
Path hard-coding bukanlah hal terbaik yang dapat Anda lakukan dengan file conf.py.
firegurafiku
18
Jika Anda memiliki struktur proyek seperti /app, /docs, ... Anda mungkin menggunakan sys.path.append(os.path.join(os.path.dirname(__name__), '..'))dan kemudian menggunakan .. automodule:: appdalam Anda .rst-file.
fnkr
3

Jika

  1. jalur akar modul disetel dengan benar di conf.py
  2. __init__.py ditempatkan dengan benar
  3. sintaks pertama benar

dan autodoc Anda masih tidak dapat menemukan modul ...

Mungkin karena dependensi dari modul tersebut tidak terpenuhi di lingkungan python Anda. Anda akan ingin memeriksa apakah semua pernyataan import berfungsi di dalam modul.

Ingako
sumber
4
Saya tidak mengerti mengapa sphinx membutuhkan dependensi, apakah itu karena kemungkinan memiliki pengujian dalam docstrings? Bisakah ini dihindari (saya tidak memerlukan paket apa pun, saya hanya ingin sphinx mengurai docstring ke html).
cglacet
Jika Anda tidak ingin mengimpor dependensi ini gunakan autodoc_mock_imports di file conf.py Anda: sphinx-doc.org/en/master/usage/extensions/…
filip stepniak
1

Saya rasa saya melakukan ini pertama kali saya mencoba menambahkan file ke toctree. Saya pikir itu karena saya meninggalkan baris kosong antara baris maxdepth dan nama file.

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

Di atas adalah file index.rst saya. stuff.rst berada di direktori yang sama seperti itu.

John Gaines Jr.
sumber
2
Kemana perginya ini? Saya memiliki index.rstdi /docs/sourcedan /ys_utils. Saya kira ini harus dalam docsversi? Saya hanya menggunakan index.rstfile default yang telah dibuat dengan sphinx-quickstart.
Rico
-1 sejak traceback terlihat jelas bahwa modul tidak ada sys.path, jadi autodoc tidak dapat menemukannya. The .rstfile yang ditemukan.
bmu
1

Saya mendapat kesalahan yang sama tetapi itu disebabkan oleh alasan yang sama sekali berbeda dari yang dijelaskan di jawaban lain.

.. automethod:: mymodule.funcArahan saya seharusnya adalah:

.. automethod:: mymodule::func`
jintan saru-
sumber
0

Anda dapat menggunakan Pweave dan noweb format untuk menghasilkan dokumen pertama yang mencakup output dari kode tertanam di dalamnya. Pada dasarnya, Anda menulis file pertama Anda, dengan kode python tertanam dalam potongan bertanda seperti ini:

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

dan Pweave akan mengeksekusi potongan-potongan tersebut, dan menggantinya dengan keluarannya dalam file pertama yang dihasilkan, yang kemudian dapat Anda gunakan dengan sphinx. Lihat contoh Pweave reST untuk detail selengkapnya tentang tampilannya.

n nothing101
sumber