无法使用 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'
]

生成 .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 和 嵌套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

如何显示 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.

解决方法

暂无找到可以解决该程序问题的有效方法，小编努力寻找整理中！

如果你已经找到好的解决方法，欢迎将解决方案带上本链接一起发送给小编。

小编邮箱:dio#foxmail.com (将#修改为@）

autodoc python python-sphinx sphinx-apidoc