我正在尝试使用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，按下标题，测试模块的页面完全空白。它只是标题，没有文档字符串或其他。
有谁知道我在这里做错了什么？我认为put .. 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 没有显示错误，但是为模块生成的文件是空白的。没有显示docstring（即使在我说它被修复之前，文档字符串被正确显示了......）。
如果我在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工作得很好...... 但我没有改变任何模块中的任何导入（我认为这可能是我模块的错误），所以我对这些结果的变化感到困惑。
很抱歉没有回答就写了这么长的问题。无论如何，我仍然期待有人知道发生了什么。
答案 0 :(得分：3)
狮身人面像腌制其环境和toctree。我有时会遇到这种“缓存”的奇怪行为。
您可以在make clean之前使用rm（make html整个builddir）。因此，从更改的文件中读取所有内容，并删除可能的错误。