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。

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

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

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

此后，您可以将自动文档指令文件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，它将使用自动模块指令从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
                        ]
    )

之后，将所有autogen输出放到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制作模板很复杂，因此灵活性较差。它仍然是有效的解决方案，并且在某些情况下（例如巨大的代码库）很有用。

我已经将an RTD compatible Example here标记为apidoc多包。

Readthedocs不显示文档字符串文档

1 个答案:

附录：