python-3.x - Pycharm 文档字符串 : code references and docstring inheritance

Question

我目前正在 Jetbrains Pycharm 2017.1.5 中完成我的项目，记录我所有的 python 3.6 类和方法，并且有几件事对我来说是关于文档字符串格式的。

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

我设法发现您可以使用 :class:`<class_name>`引用一个类，但 :class:`<class.method>`不起作用，类似命名的结构，如 :func:`<func_name>`不要创建超链接。我也看过:ref:`<name>`出现，但那个也不起作用。

(如果不是因为这个错误，我会在心跳中切换到 Epytext(它有我想要的一切，而且它更简单):Ctrl + Q 帧中的 You need configured Python 2 SDK to render Epydoc docstrings。)

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

事实证明，做一件如此简单的事情是非常复杂的。因此，任何帮助将不胜感激!

Answer 1

I want to link to other methods / functions / classes from some of the docstrings, but I cannot figure out how to do this.

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

您可能(明确地或通过某些工具隐含地)使用 the Sphinx system – Docutils 的超集 – 允许(在许多其他功能中)不同文档字符串之间的引用。

狮身人面像 defines several Docstring “roles” (反引号文本前的 :foo:)用于不同的目的:

doc , 对整个文档的引用。

ref ，任意交叉引用。

… 很多其他的。

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

• :py:mod:

  Reference a module; a dotted name may be used. This should also be used for package names.

• :py:func:

  Reference a Python function; dotted names may be used. The role text needs not include trailing parentheses to enhance readability; they will be added automatically by Sphinx if the add_function_parentheses config value is True (the default).

• :py:data:

  Reference a module-level variable.

• :py:const:

  Reference a “defined” constant. This may be a Python variable that is not intended to be changed.

• :py:class:

  Reference a class; a dotted name may be used.

• :py:meth:

  Reference a method of an object. The role text can include the type name and the method name; if it occurs within the description of a type, the type name can be omitted. A dotted name may be used.

• :py:attr:

  Reference a data attribute of an object.

• :py:exc:

  Reference an exception. A dotted name may be used.

• :py:obj:

  Reference an object of unspecified type.