Pycharm docstring:代码引用和docstring继承

Question

我目前正在浏览Jetbrains Pycharm 2017.1.5中的项目,记录我所有的python 3.6类和方法,并且有几个关于docstring格式的东西.

我想链接到某些文档字符串中的其他方法/函数/类,但我无法弄清楚如何执行此操作.restructuredText的文档非常非常广泛,但它没有说任何关于使用Pycharm引用其他文档字符串的内容.实际上,该页面中的绝大部分片段甚至都不能在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帧中.)

如果有一种方法可以继承子类/重写方法中的docstring,那么它也会非常有用.如果您将docstring留空,Pycharm会自动执行此操作,这使我认为可以手动执行此操作.但是,我再也找不到任何相关信息.

事情变得非常复杂,如此简单.所以,任何帮助将不胜感激!

Answer 1

\n

我想从一些文档字符串链接到其他方法/函数/类，但我不知道如何做到这一点。

\n

\n\n

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

\n\n

您可能（显式地或通过某些工具隐式地）使用Sphinx 系统\xe2\x80\x93 Docutils \xe2\x80\x93 的超集，以允许（以及许多其他功能）在不同文档字符串之间进行引用。

\n\n

Sphinx出于不同的目的定义了几个 Docstring \xe2\x80\x9croles\xe2\x80\x9d（:foo:反引号引用的文本之前）：

\n\n

\n
• doc，对整个文档的引用。
\n
• ref，任意交叉引用。
\n
• \xe2\x80\xa6 还有很多其他的。
\n

\n\n

对于特定的 Python 代码， \xe2\x80\x9cdomain\xe2\x80\x9d对于 Python 代码文档字符串py有其自己的特定角色集：

\n\n

\n

\n

• :py:mod:

  \n\n

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

\n

• :py:func:

  \n\n

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

\n

• :py:data:

  \n\n

  引用模块级变量。

\n

• :py:const:

  \n\n

  引用 \xe2\x80\x9cdefine\xe2\x80\x9d 常量。这可能是一个不打算更改的 Python 变量。

\n

• :py:class:

  \n\n

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

\n

• :py:meth:

  \n\n

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

\n

• :py:attr:

  \n\n

  引用对象的数据属性。

\n

• :py:exc:

  \n\n

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

\n

• :py:obj:

  \n\n

  引用未指定类型的对象。

\n

\n

\n