Readthedocs无法显示docstring文档。

Question

我已经按照Readthedocs上的入门指南，并使用Sphinx使用autodoc为我的Python包创建文档，链接在https://github.com/akdiem/bloodflow上（相关文档.rst文件在docs文件夹中）。

Readthedocs构建已通过，可以在https://bloodflow.readthedocs.io/en/latest/找到。

Readthedocs没有显示我的代码部分的docstring文档，但对我来说一切看起来都应该没问题。为什么没有显示？

- glanne

---

如果有其他人遇到同样的问题，我想提供一点帮助。当我查看我的实时文档时，关闭广告拦截器就解决了这个问题... - astronat

Answer 1

Autodoc是Sphinx的一个扩展程序，在构建时查看.rst文件中的automodule指令引用，导入和识别Python代码，然后将其docstring转换为html。

由于您的模块没有通过setup.py安装到环境中， 因此需要手动导入您的模块，所以您需要在conf.py中为sphinx提供上下文：

import os
import sys
#Location of Sphinx files
sys.path.insert(0, os.path.abspath('./../..'))

在这种情况下，您的顶级模块的绝对路径比conf.py文件高2个层级。

完成后，您可以将您的autodoc指令文件arteryfe.rst添加回index.rst toctrees，然后它就会显示出来了。

Welcome to artery.fe's documentation!
=====================================

.. toctree::
    :maxdepth: 2
    :caption: Contents:

    arteryfe
    getting_started
    tutorial
    theory
    numerical

如果您想进行环境安装，您将需要勾选选项以使ReadTheDocs使用虚拟环境并利用site-packages。

---

附录:

这是另一种方法，如果您有多个软件包，则尤其有用。

在更大的代码库中手动创建带有Autodoc指令的文件可能会有问题，因此我们有了Sphinx Apidoc - 它是补充Autodoc扩展的一个扩展。

这意味着您可以使用首选选项运行sphinx-apidoc，它将从您的Docstrings生成.rst文件，并生成为html的automodule指令 - 但这也可以在RTD的构建期间通过conf.py完成。

例如，这将使Sphinx在构建时生成一个automodule arteryfe.rst文件在/source/_autogen中:

import os
import sys
#Location of Sphinx files
sys.path.insert(0, os.path.abspath('./../..'))

import sphinx.apidoc
def setup(app):
    sphinx.apidoc.main(['-f', #Overwrite existing files
                        '-T', #Create table of contents
                        #'-e', #Give modules their own pages
                        '-E', #user docstring headers
                        #'-M', #Modules first
                        '-o', #Output the files to:
                        './source/_autogen/', #Output Directory
                        './../arteryfe', #Main Module directory
                        ]
    )

接下来只需将自动生成的所有输出添加到目录树中即可。

Welcome to artery.fe's documentation!
=====================================

.. toctree::
    :maxdepth: 2
    :caption: Contents:

    getting_started
    tutorial
    theory
    numerical

.. toctree::
    :maxdepth: 2
    :glob:
    :caption: Code:

    _autogen/*

由于为 apidoc 制作模板很复杂，因此它的灵活性稍有一点不足。但在某些情况下（例如大型代码库），仍然是一个有效的解决方案并且非常有用。

我在这里涂鸦了一个支持多个 apidoc 包的 RTD 兼容示例。

- lucasgcb