CODEWITHSUNDEEP
python-3.xpycharmrestructuredtextdocstring
Cynadyde
Cynadyde

Reputation: 383

Pycharm docstring: code references and docstring inheritance

I'm currently going through my project in Jetbrains Pycharm 2017.1.5, documenting all my python 3.6 classes and methods, and several things stand out to me about the docstring format.

I want to link to other methods / functions / classes from some of the docstrings, but I cannot figure out how to do this. The documentation for restructuredText is very, very extensive, but it doesn't say anything about referencing other docstrings with Pycharm. In fact, the vast majority of the snippets from that page do not even work in Pycharm. (Why is that?)

I've managed to find that you can use :class:`<class_name>` to reference a class, but :class:`<class.method>`does not work, and similarly named constructs like :func:`<func_name>` do not create a hyperlink. I've also seen :ref:`<name>` come up, but that one doesn't work either.

(I would switch to Epytext (it has everything I want, plus it's much simpler) in a heartbeat if not for this error: You need configured Python 2 SDK to render Epydoc docstrings in the Ctrl + Q frame.)

It would also be extremely helpful if there was a way to inherit the docstring in subclasses / overridden methods. Pycharm does this automatically if you leave the docstring blank, which makes me think it is possible to do it manually. But, again, I can't find any information on it.

It's turning out to be mind-blowingly complicated to do something so, so simple. So, any help will be appreciated!

Upvotes: 22

Views: 6341

Answers (1)

bignose
bignose

Reputation: 32309

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

You're correct that the reStructuredText documentation does not cover this, because it's not a feature of reStructuredText.

Likely you are (explicitly, or implicitly via some tool) using the Sphinx system – a superset of Docutils – to allow (among many other features) references between different docstrings.

Sphinx defines several Docstring “roles” (the :foo: before the backtick-quoted text) for different purposes:

  • doc, a reference to an entire document.
  • ref, an arbitrary cross-reference.
  • … many others.

For specifically Python code, the “domain” py has its own specific set of 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.

Upvotes: 5

Related Questions