2

我正在学习如何使用Sphinx为我的代码创建文档。在我看到一些这样的例子之后：

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0: return complex_zero
    ...

评论中使用什么语言让 Sphinx 理解并抓住它们？如果没有这种语法和逻辑，Sphinx 在我的代码中看不到注释，并且当我生成 HTML 时，模块是空的。

这里有一个例子：

在此处输入图像描述

4

1 回答 1

2

您必须将注释与文档字符串（全称为“文档字符串”）区分开来。

请参阅PEP8 并注意文档字符串仅适用于模块、函数、类和方法。对于提到的对象，您可以申请your_object.__doc__以编程方式检索文档字符串；变量没有docstrings。

关于你的例子：

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)

    """

Sphinx将检索的文档字符串中可以使用 3 种流行的语法：

  1. reST 是基本语法。
  2. Numpy 样式的文档字符串。
  3. 谷歌风格的文档字符串。

规范是在Numpy或Google 风格之间进行选择（目前它们提供更好的可读性和功能，以及风格指南）。要使这些工作，您需要使用Sphinx-Napoleon 扩展，查看官方文档中的概述。

于 2020-06-23T23:30:30.373 回答