我正在尝试开始使用 Sphinx 来记录我的一些小项目， 但我似乎无法让它工作。
我已经四处搜索，但到目前为止我尝试的所有方法都没有修复导入错误。
这正是我正在做的事情:
giacomo@Giacomo-PC:~$ mkdir sphinx-test
giacomo@Giacomo-PC:~$ cd sphinx-test/
giacomo@Giacomo-PC:~/sphinx-test$ mkdir -p src/package doc
giacomo@Giacomo-PC:~/sphinx-test$ touch src/package/__init__.py
giacomo@Giacomo-PC:~/sphinx-test$ echo '"""Docstring 1"""
> class Test(object):
> """Docstring 2"""
>
> def method(self):
> """Docstring 3"""
> pass
> ' > src/package/testing.py
giacomo@Giacomo-PC:~/sphinx-test$ cd doc
giacomo@Giacomo-PC:~/sphinx-test/doc$ sphinx-quickstart
Welcome to the Sphinx 1.0.1 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Enter the root path for documentation.
> Root path for the documentation [.]:
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/N) [n]: y
Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.
> Name prefix for templates and static dir [_]:
The project name will occur in several places in the built documentation.
> Project name: testing
> Author name(s): A B
Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1. If you don't need this dual structure,
just set both to the same value.
> Project version: 0.1
> Project release [0.1]:
The file name suffix for source files. Commonly, this is either ".txt"
or ".rst". Only files with this suffix are considered documents.
> Source file suffix [.rst]:
One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]:
Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/N) [n]:
Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/N) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/N) [n]: y
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/N) [n]:
> coverage: checks for documentation coverage (y/N) [n]:
> pngmath: include math, rendered as PNG images (y/N) [n]:
> jsmath: include math, rendered in the browser by JSMath (y/N) [n]:
> ifconfig: conditional inclusion of content based on config values (y/N) [n]:
> viewcode: include links to the source code of documented Python objects (y/N) [n]:
A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (Y/n) [y]:
> Create Windows command file? (Y/n) [y]:
Finished: An initial directory structure has been created.
You should now populate your master file ./source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
giacomo@Giacomo-PC:~/sphinx-test/doc$ vim source/conf.py # sys.path.append('../../src')
giacomo@Giacomo-PC:~/sphinx-test/doc$ echo '
> Title
> =====
>
> .. automodule:: package.testing
> :members:
>
> ..autoclass:: package.testing.Test
> :members:
>
> .. automethod:: package.testing.Test.method
> ' > source/testing.rst
giacomo@Giacomo-PC:~/sphinx-test/doc$ vim source/testing.rst #correct the typo: ..autoclass -> .. autoclass
giacomo@Giacomo-PC:~/sphinx-test/doc$ vim source/index.rst #add testing in the toctree
giacomo@Giacomo-PC:~/sphinx-test/doc$ make html
sphinx-build -b html -d build/doctrees source build/html
Making output directory...
Running Sphinx v1.0.1
loading pickled environment... not yet created
building [html]: targets for 2 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
reading sources... [100%] testing
/home/giacomo/sphinx-test/doc/source/testing.rst:5: (WARNING/2) autodoc can't import/find module 'package.testing', it reported error: "No module named package.testing", please check your spelling and sys.path
/home/giacomo/sphinx-test/doc/source/testing.rst:8: (WARNING/2) autodoc can't import/find class 'package.testing.Test', it reported error: "No module named package.testing", please check your spelling and sys.path
/home/giacomo/sphinx-test/doc/source/testing.rst:11: (WARNING/2) autodoc can't import/find method 'package.testing.Test.method', it reported error: "No module named package.testing", please check your spelling and sys.path
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] testing
writing additional files... genindex search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded, 3 warnings.
Build finished. The HTML pages are in build/html.
我也尝试过这个:
giacomo@Giacomo-PC:~/sphinx-test/doc$ rm build/html/*
rm: impossibile rimuovere "build/html/_sources": È una directory
rm: impossibile rimuovere "build/html/_static": È una directory
giacomo@Giacomo-PC:~/sphinx-test/doc$ PYTHONPATH="../src" make html
sphinx-build -b html -d build/doctrees source build/html
Running Sphinx v1.0.1
loading pickled environment... done
building [html]: targets for 2 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
preparing documents... done
writing output... [100%] testing
writing additional files... genindex search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded.
Build finished. The HTML pages are in build/html.
输出看起来令人鼓舞，但实际上如果我打开index.html，按标题，测试模块的页面完全是空白的。它只有标题，没有文档字符串或其他内容。
有谁知道我在这里做错了什么？我认为放置 .. automodule + .. autoclass 会自动显示这些文档字符串，但我看不到它们。
编辑:
已修复，但我不明白为什么...... 这就是我这次所做的(我觉得和以前一模一样)
giacomo@Giacomo-PC:~$ mkdir sphinx-tests
giacomo@Giacomo-PC:~$ cd sphinx-tests/
giacomo@Giacomo-PC:~/sphinx-tests$ mkdir -p src/package doc
giacomo@Giacomo-PC:~/sphinx-tests$ touch src/package/__init__.py
giacomo@Giacomo-PC:~/sphinx-tests$ echo '"""Docstring 1"""
> class Test(object):
> """Docstring 2"""
> def method(self):
> """Docstring 3"""
> pass
> ' > src/package/testing.py
giacomo@Giacomo-PC:~/sphinx-tests$ cd doc
giacomo@Giacomo-PC:~/sphinx-tests/doc$ sphinx-quickstart
Welcome to the Sphinx 1.0.1 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Enter the root path for documentation.
> Root path for the documentation [.]:
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/N) [n]: y
Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.
> Name prefix for templates and static dir [_]:
The project name will occur in several places in the built documentation.
> Project name: Test
> Author name(s): A B
Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1. If you don't need this dual structure,
just set both to the same value.
> Project version: 0.1
> Project release [0.1]:
The file name suffix for source files. Commonly, this is either ".txt"
or ".rst". Only files with this suffix are considered documents.
> Source file suffix [.rst]:
One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]:
Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/N) [n]:
Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/N) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/N) [n]: y
> intersphinx: link between Sphinx documentation of different projects (y/N) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/N) [n]:
> coverage: checks for documentation coverage (y/N) [n]:
> pngmath: include math, rendered as PNG images (y/N) [n]:
> jsmath: include math, rendered in the browser by JSMath (y/N) [n]:
> ifconfig: conditional inclusion of content based on config values (y/N) [n]:
> viewcode: include links to the source code of documented Python objects (y/N) [n]:
A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (Y/n) [y]:
> Create Windows command file? (Y/n) [y]:
Finished: An initial directory structure has been created.
You should now populate your master file ./source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
giacomo@Giacomo-PC:~/sphinx-tests/doc$ echo '
> Title
> =====
>
> .. automodule:: package.testing
> :members:
>
> .. autoclass:: package.testing.Test
> :members:
>
> .. automethod:: package.testing.Test.method
> ' > source/testing.rst
giacomo@Giacomo-PC:~/sphinx-tests/doc$ vim source/index.rst # add testing to toctree
giacomo@Giacomo-PC:~/sphinx-tests/doc$ vim source/conf.py #sys.path.append('../../src')
giacomo@Giacomo-PC:~/sphinx-tests/doc$ make html
sphinx-build -b html -d build/doctrees source build/html
Making output directory...
Running Sphinx v1.0.1
loading pickled environment... not yet created
building [html]: targets for 2 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
reading sources... [100%] testing
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] testing
writing additional files... genindex py-modindex search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded.
Build finished. The HTML pages are in build/html.
giacomo@Giacomo-PC:~/sphinx-tests/doc$
顺便说一句:抱歉有很多行代码。
编辑2:
我发现，如果清除 build/html 目录，autodoc 不会显示任何错误但是为模块生成的文件是空白的。没有显示文档字符串(即使之前我说它已修复，文档字符串也正确显示了......)。
如果我在 build/html 文件夹中保留空文件夹 _sources 和 _static，那么 autodoc 将找不到模块。
真的，我不明白发生了什么。
编辑3:
好吧，这太疯狂了:
giacomo@Giacomo-PC:~/Progetti/TagEditor/doc$ rm -fr build/html/*
giacomo@Giacomo-PC:~/Progetti/TagEditor/doc$ make html
sphinx-build -b html -d build/doctrees source build/html
[...]taglib
/home/giacomo/Progetti/TagEditor/doc/source/fields.rst:4: (WARNING/2) autodoc can't import/find module 'taglib.fields', it reported error: "No module named taglib.fields", please check your spelling and sys.path
/home/giacomo/Progetti/TagEditor/doc/source/taglib.rst:4: (WARNING/2) autodoc can't import/find module 'taglib', it reported error: "No module named taglib", please check your spelling and sys.path
[...]
build succeeded, 2 warnings.
Build finished. The HTML pages are in build/html.
giacomo@Giacomo-PC:~/Progetti/TagEditor/doc$ rm -fr build/html/*
giacomo@Giacomo-PC:~/Progetti/TagEditor/doc$ make html
sphinx-build -b html -d build/doctrees source build/html
[...]
build succeeded.
Build finished. The HTML pages are in build/html.
看起来程序不是确定性的，而是随机“工作”的(模块文档文件仍然是空的)。
现在我开始认为更改软件可能会更好。
编辑4:
我重写了其中一个模块，现在 autodoc 工作得很好...... 但我没有更改任何模块中的任何导入(我想这可能是我的模块的错)，所以我对结果的这些变化感到非常困惑。
抱歉写了这么长的问题却没有答案。不管怎样，我仍然期待有人知道发生了什么事。
最佳答案
Sphinx 腌制它的环境和 toctree。我有时会遇到这种“缓存”的奇怪行为。
您可以在make html之前使用make clean(这将rm整个builddir)。因此，所有内容都会从您更改的文件中读取，并删除可能的错误。
关于python - 尝试自动文档包时出现导入错误，我们在Stack Overflow上找到一个类似的问题： https://stackoverflow.com/questions/9912539/