在Sphinx中，如何包括位于模块中但类和方法之外的文档字符串/注释 [英] In Sphinx, how to include docstrings/comments located in a module, but outside of class and methods

问题描述

我的包裹中有一个 utils 模块。它由几个不需要实例化的杂项独立方法组成。

I have a utils module in my package. It consists of several misc standalone methods that do not require instantiation.

我想在此 utils 文件，例如：

import os
import json

"""
Miscellaneous methods that help in <<blah blah>>
Does not require explicit instantiation.

The following actions can be performed:
===============   ===============
Action            Method
===============   ===============
Get a             :meth:`methoda`
Get b             :meth:`methodb`
"""

def methoda(data):
    "Gets A ..."
    ...

def methodb(data):
    "Gets B ..."
    ...

如上所示，文档字符串具有包含各个方法链接的表。目前，我的 index.rst 的这一部分包括 utils ：

As seen above, the docstring has a table including links to the individual methods. Currently, my index.rst has this part to include utils:

Utilities
============
.. automodule:: packagename.utils
   :members:

当前，我得到了文档中正确显示的各个方法的文档字符串，但不是顶级文档模块的文档字符串（在任何类或方法之外）。使狮身人面像包含上述内容的最佳方法是什么？

Currently, I get the docstrings of the individual methods properly displayed in the documentation, but not the top-level docstring of the module (outside of any class or method). What is the best way to have have sphinx include the above?

一个选项可能是将顶级文档字符串移至该文件之外，例如移至 index.rst 等等。但我宁愿不这样做，并将其保留在源文件中。

One option might be to move the top-level docstring outside of this file, such as to index.rst etc. But I would prefer not doing this, and retain it within the source file.

推荐答案

感谢jonsharpe的评论，并引导我找到执行此操作的正确方法。

Thanks to jonsharpe for his comment, and leading me to the proper way of doing this.

为了供其他人将来参考，我基本上将文档字符串移到了文件的开头：

For future reference by others, I basically moved the docstrings to the start of the file:

"""
Miscellaneous methods that help in <<blah blah>>
Does not require explicit instantiation.

The following actions can be performed:
===============   ===============
Action            Method
===============   ===============
Get a             :meth:`methoda`
Get b             :meth:`methodb`
"""

import os
import json

def methoda(data):
    "Gets A ..."
    ...

def methodb(data):
    "Gets B ..."
    ...

就是这样！一切正常。

这篇关于在Sphinx中，如何包括位于模块中但类和方法之外的文档字符串/注释的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！