21

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!

bgse
  • 8,237
  • 2
  • 37
  • 39
Cynadyde
  • 373
  • 3
  • 9
  • Do you want references to work before or after generating documentation, such as through Sphinx? Sphinx can generate output, such as HTML, from reStructuredText that supports referencing for any Python object through the [`autodoc` extension](http://www.sphinx-doc.org/en/stable/ext/autodoc.html). – Steve Piercy Nov 23 '17 at 01:53
  • I would like them to work before exporting the documentation as HTML, but if it can't be done it's not going to kill me or anything. Sphinx is probably my best option. It just frustrates me that these two simple things don't seem to be possible in the documentation preview, and now I have to know for sure. – Cynadyde Nov 23 '17 at 04:57
  • Please ask about one thing at a time. The docstring inheritance problem should be in a separate question. – mzjn Nov 23 '17 at 12:40

1 Answers1

5

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.

bignose
  • 30,281
  • 14
  • 77
  • 110
  • 5
    OP asks about `PyCharm` specifically and this answer, as helpful as it is, says nothing about PyCharm. – z33k Nov 10 '21 at 13:21