Readthedocs 不显示文档字符串文档

Question

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

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

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

Answer 1

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

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

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

在这种情况下，顶级模块的绝对路径位于 conf.py 文件上方 2 层。

之后，您可以将 autodoc 指令文件arterfe.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。conf.py然而，这也可以在 RTD 的构建期间完成。

例如，这将使 Sphinx在构建时生成一个自动模块arteryfe.rst文件：/source/_autogen

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

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

    arteryfe
    getting_started
    tutorial
    theory
    numerical

之后，只需将所有 autogen 输出放入目录树中即可。

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 兼容示例。