如何解决无法使用 sphinx 为嵌套的 python 模块生成 html 文档
我正在使用 sphinx 使用我的 Python 模块中的 docstring 自动生成 html。为此，我使用了 sphinx 的名为“sphinxdoc/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'
]
docker run --rm -v /path/to/project/DocString_Project:/docs sphinxdoc/sphinx sphinx-apidoc -o /docs/source ../docs/allmodules
docker run --rm -v /path/to/project/DocString_Project:/docs sphinxdoc/sphinx make html
问题 生成的 HTML 文档正确显示最外层模块的文档字符串； docstring.py 和 sphinxtutorial.py 但不显示 nested1 和 嵌套2。但是，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
注意：嵌套的 py 模块与父目录中的对应模块完全相同，即 docstring.py 与 docstringnested1.py 和 docstringnested2.py 相同
==================
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.
版权声明：本文内容由互联网用户自发贡献，该文观点与技术仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容， 请发送邮件至 dio@foxmail.com 举报，一经查实，本站将立刻删除。
