python-sphinx - Readthedocs 不显示文档字符串文档

Question

我已遵循 Readthedocs 上的入门指南，并使用 Sphinx 使用 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

In the case you ever want to make an environment installation, you'll have to tick the option for ReadTheDocs to use a virtualenvironment and utilize site-packages.

附录:

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

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

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

例如，这将使 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
                        ]
    )

之后，只需将所有自动生成输出到您的目录树中。

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

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

    getting_started
    tutorial
    theory
    numerical

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

    _autogen/*

它有点不灵活，因为为 apidoc 制作模板很复杂。它仍然是一个有效的解决方案，并且在某些情况下很有用(即巨大的代码库)。

我写了 an RTD compatible Example here对于 apidoc 多包。