Readthedocs不显示docstring文档

Question

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

readthedoc构建通过并在https://bloodflow.readthedocs.io/en/latest/上找到

Readthedocs没有显示任何作为我的代码一部分的文档字符串文档，但对我来说，一切看起来都应该如此。为什么不呢？

Answer 1

Autodoc是一个Sphinx扩展，在构建期间查看.rst文件中的自动模块指令引用，导入并识别Python代码，然后将其文档字符串转换为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的选项以使用虚拟环境并使用站点包。

---

附录：

这是另一种方法，如果您有多个包，则特别有用。

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

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

例如，这将使Sphinx在构建期间在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
                        ]
    )

之后，只需将所有自动输出全部输入到您的toctree中。

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 multipackages潦草地写了an RTD compatible Example here。