Pycharm docstring:代码引用和docstring继承

问题描述 投票:10回答:1

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

我想链接到某些文档字符串中的其他方法/函数/类,但我无法弄清楚如何执行此操作。 restructuredText的文档非常非常广泛,但它没有说任何关于使用Pycharm引用其他文档字符串的内容。实际上,该页面中的绝大部分片段甚至都不能在Pycharm中运行。 (这是为什么?)

我设法发现你可以使用:class:`<class_name>`来引用一个类,但:class:`<class.method>`does不起作用,类似命名的构造如:func:`<func_name>`不会创建超链接。我也看到:ref:`<name>`出现,但那个也不起作用。

(如果没有这个错误,我会切换到Epytext(它有我想要的一切,加上它更简单):在Ctrl + Q帧中使用You need configured Python 2 SDK to render Epydoc docstrings。)

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

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

python-3.x pycharm restructuredtext docstring
1个回答
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: 引用未指定类型的对象。
© www.soinside.com 2019 - 2024. All rights reserved.