我正在使用 sphinx 使用我的 python 模块中的 docstring 自动生成 html。为此，我使用了名为“sphinxdoc/sphinx”的 sphinx 的 docker 镜像。我通过将我的 python 项目（在 DocString_Project 目录中）映射为一个卷来运行 sphinx。步骤如下。
快速开始：
docker run -it --rm -v /path/to/project/DocString_Project:/docs sphinxdoc/sphinx sphinx-quickstart将 conf.py 文件编辑为：
import sys
sys.path.insert(0, os.path.abspath('../allmodules'))
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.viewcode'
]
- 生成 .rst 文件。
docker run --rm -v /path/to/project/DocString_Project:/docs sphinxdoc/sphinx sphinx-apidoc -o /docs/source ../docs/allmodules
这会生成 .rst 文件，如下所示。
在 index.rst toctree::下面添加模块
制作html
docker run --rm -v /path/to/project/DocString_Project:/docs sphinxdoc/sphinx make html
问题生成的 HTML 文档正确显示了最外层模块的文档字符串；docstring.py和sphinxtutorial.py但不显示nested1和nested2内任何嵌套模块的文档。但是，sphinx apidoc 确实检测到它们的存在。
Folders
DocString_Project:
------build
------source
--------conf.py
--------index.rst
--------modules.rst
--------allmodules.rst
--------allmodules.nested1.rst
--------allmodules.nested1.nested2.rst
------make.bat
------Makefile
------allmodules
--------__init__.py
--------docstring.py
--------sphinxtutorial.py
--------nested1
-------- __init__.py
-------- docstringnested1.py
-------- sphinxtutorialnested1.py
-------- nested2
--------__init__.py
--------docstringnested2.py
--------sphinxtutorialnested2.py
如何显示来自nested1 和nested2 下模块的文档？
注意：嵌套的 py 模块与父目录中的对应模块完全相同，即 docstring.py 与 docstringnested1.py 和 docstringnested2.py 相同
更新：.rst 文件的内容： allmodules.rst
==================
Subpackages
-----------
.. toctree::
:maxdepth: 4
allmodules.nested1
Submodules
----------
allmodules.docstring module
---------------------------
.. automodule:: allmodules.docstring
:members:
:undoc-members:
:show-inheritance:
allmodules.sphinxtutorial module
--------------------------------
.. automodule:: allmodules.sphinxtutorial
:members:
:undoc-members:
:show-inheritance:
Module contents
---------------
.. automodule:: allmodules
:members:
:undoc-members:
:show-inheritance:
allmodules.nested1.rst
allmodules.nested1 package
==========================
Subpackages
-----------
.. toctree::
:maxdepth: 4
allmodules.nested1.nested2
Submodules
----------
allmodules.nested1.docstringnested1 module
------------------------------------------
.. automodule:: allmodules.nested1.docstringnested1
:members:
:undoc-members:
:show-inheritance:
allmodules.nested1.sphinxtutorialnested1 module
-----------------------------------------------
.. automodule:: allmodules.nested1.sphinxtutorialnested1
:members:
:undoc-members:
:show-inheritance:
Module contents
---------------
.. automodule:: allmodules.nested1
:members:
:undoc-members:
:show-inheritance:
allmodules.nested1.nested2.rst
allmodules.nested1.nested2 package
==================================
Submodules
----------
allmodules.nested1.nested2.docstringnested2 module
--------------------------------------------------
.. automodule:: allmodules.nested1.nested2.docstringnested2
:members:
:undoc-members:
:show-inheritance:
allmodules.nested1.nested2.sphinxtutorialnested2 module
-------------------------------------------------------
.. automodule:: allmodules.nested1.nested2.sphinxtutorialnested2
:members:
:undoc-members:
:show-inheritance:
Module contents
---------------
.. automodule:: allmodules.nested1.nested2
:members:
:undoc-members:
:show-inheritance:
制作 html 错误/警告
docker run --rm -v /Users/abhinav/PycharmProjects/DocString_Project:/docs sphinxdoc/sphinx make html
Running Sphinx v4.0.2
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 4 changed, 0 removed
reading sources... [ 25%] allmodules
reading sources... [ 50%] allmodules.nested1
reading sources... [ 75%] allmodules.nested1.nested2
reading sources... [100%] index
WARNING: autodoc: failed to import module 'docstring' from module 'allmodules'; the following exception was raised:
No module named 'allmodules'
WARNING: autodoc: failed to import module 'sphinxtutorial' from module 'allmodules'; the following exception was raised:
No module named 'allmodules'
WARNING: autodoc: failed to import module 'allmodules'; the following exception was raised:
No module named 'allmodules'
WARNING: autodoc: failed to import module 'nested1.docstringnested1' from module 'allmodules'; the following exception was raised:
No module named 'allmodules'
WARNING: autodoc: failed to import module 'nested1.sphinxtutorialnested1' from module 'allmodules'; the following exception was raised:
No module named 'allmodules'
WARNING: autodoc: failed to import module 'nested1' from module 'allmodules'; the following exception was raised:
No module named 'allmodules'
WARNING: autodoc: failed to import module 'nested1.nested2.docstringnested2' from module 'allmodules'; the following exception was raised:
No module named 'allmodules'
WARNING: autodoc: failed to import module 'nested1.nested2.sphinxtutorialnested2' from module 'allmodules'; the following exception was raised:
No module named 'allmodules'
WARNING: autodoc: failed to import module 'nested1.nested2' from module 'allmodules'; the following exception was raised:
No module named 'allmodules'
/docs/source/index.rst:9: WARNING: toctree contains reference to nonexisting document ' modules'
looking for now-outdated files... none found
pickling environment... done
checking consistency... /docs/source/modules.rst: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [ 20%] allmodules
writing output... [ 40%] allmodules.nested1
writing output... [ 60%] allmodules.nested1.nested2
writing output... [ 80%] index
writing output... [100%] modules
generating indices... genindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 11 warnings.
The HTML pages are in build/html.