Pycharm docstring：代码引用和 docstring 继承

Question

我目前正在浏览我在 Jetbrains Pycharm 2017.1.5 中的项目，记录我所有的 python 3.6 类和方法，关于 docstring 格式的一些事情对我来说很突出。

我想从一些文档字符串链接到其他方法/函数/类，但我不知道如何做到这一点。 restructuredText 的文档非常非常广泛，但它没有说明使用 Pycharm 引用其他文档字符串。事实上，该页面中的绝大多数 sn-ps 甚至在 Pycharm 中都不起作用。 （这是为什么呢？）

我设法发现您可以使用:class:`<class_name>` 来引用一个类，但是:class:`<class.method>` 不起作用，并且类似名称的构造（如:func:`<func_name>`）不会创建超链接。我也看到:ref:`<name>` 出现了，但那个也不起作用。

（如果不是因为这个错误，我会立即切换到Epytext（它拥有我想要的一切，而且更简单）：You need configured Python 2 SDK to render Epydoc docstrings 在 Ctrl + Q 框架中。）

如果有一种方法可以在子类/重写方法中继承文档字符串，那也将非常有帮助。如果您将文档字符串留空，Pycharm 会自动执行此操作，这让我认为可以手动执行此操作。但是，同样，我找不到任何关于它的信息。

事实证明，这样做非常复杂，如此简单。所以，任何帮助将不胜感激！

Answer 1

我想从一些文档字符串中链接到其他方法/函数/类，但我不知道该怎么做。

reStructuredText 文档没有涵盖这一点是正确的，因为它不是 reStructuredText 的功能。

您可能（通过某些工具显式或隐式地）使用the Sphinx system（Docutils 的超集）来允许（在许多其他功能中）不同文档字符串之间的引用。

Sphinx defines several Docstring “roles”（反引号引用文本前的:foo:）用于不同目的：

• doc，对整个文档的引用。
• ref，任意交叉引用。
• ……还有很多其他的。

对于特定的 Python 代码，“域”py 有自己特定的一组 roles for Python code docstrings：

• :py:mod:

  引用一个模块；可以使用带点的名称。这也应该用于包名称。

• :py:func:

  引用一个 Python 函数；可以使用带点的名称。角色文本不需要包含尾括号以增强可读性；如果 add_function_parentheses 配置值为 True（默认值），它们将由 Sphinx 自动添加。

• :py:data:

  引用模块级变量。

• :py:const:

  引用一个“已定义”的常量。这可能是一个不打算更改的 Python 变量。

• :py:class:

  引用一个类；可以使用带点的名称。

• :py:meth:

  引用对象的方法。角色文本可以包括类型名和方法名；如果它出现在类型的描述中，则可以省略类型名称。可以使用带点的名称。

• :py:attr:

  引用对象的数据属性。

• :py:exc:

  引用异常。可以使用带点的名称。

• :py:obj:

  引用未指定类型的对象。