我正在尝试开始使用 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，按 Title 测试模块的页面是完全空白的。它只是有标题，没有文档字符串或其他任何东西。
有谁知道我在这里做错了什么？我认为放置 .. 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 不会显示任何错误，但为模块生成的文件是空白的。没有显示文档字符串（即使在我说它已修复之前，文档字符串已正确显示......）。
如果我将空文件夹 _sources 和 _static 留在 build/html 文件夹中，则 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 可以完美运行...但是我没有更改任何模块中的任何导入（我认为这可能是我的模块的错），所以我对结果的这些变化感到非常困惑。
很抱歉写了这么长的问题没有答案。无论如何，我仍然期待有人知道发生了什么。