8

I'm just trying to get a better feel for the layout of Python docstrings (Between the """ """)

I've seen docstrings with different layouts...such as...

"""
@DESCRIPTION
Ive seen tags STARTING with an at-sign

:DESCRIPTION:
Tags with colons

DESCRIPTION
And tags with nothing

"""

Do any of these have functional action? Is the @ associated with Elixir? Or are these just preferences amongst developers? I've looked through the style guide for docstrings, but can't see where it addresses such things...

Thanks!

daouzli
  • 15,288
  • 1
  • 18
  • 17
RightmireM
  • 2,381
  • 2
  • 24
  • 42

2 Answers2

10

Formats

Python docstrings can be written following several formats:

- Javadoc

Historically a javadoc like style was prevalent. It was used by Epydoc (with the called Epytext format) to generate documentation.

Example:

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

- reST

Nowadays, the probably more prevalent format is the reStructuredText (reST) format that is used by Sphinx to generate documentation.

Example:

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

- Google

Google has his own format that is quite used. It also can be interpreted by Sphinx. Note that Numpy recommend to follow their own numpydoc based on Google format and usable by Sphinx.

Example:

"""
This is a groups style docs.

Parameters:
    param1 - this is the first param
    param2 - this is a second param

Returns:
    This is a description of what is returned

Raises:
    KeyError - raises an exception
"""

Converting/Generating

It is possible to use a tool like Pyment to automatically generate docstrings to a Python project not yet documented, or to convert existing docstrings (can be mixing several formats) from a format to an other one.

Note: The examples are taken from the Pyment documentation. You can see this tuto for more informations about docstrings.

daouzli
  • 15,288
  • 1
  • 18
  • 17
  • Great answer. But I've just spent over an hour trying to convert reST-formatted pydocs into something like HTML or Markdown, and I'm surprised by the amount of setup that's apparently involved, e.g. for Sphinx. I imagined some utility could do this straight out of the box. Do you know of such a tool, or could you point to some clear steps? Thanks! – Michael Scheper Sep 18 '19 at 17:08
  • @MichaelScheper you can have a look to [this thread](https://stackoverflow.com/questions/26587763/how-to-generate-documentation-using-pydoc) – daouzli Sep 19 '19 at 14:45
3

If you want to turn the docstrings into documentation, you can add the extra markup to help the documentation tool you are using apply additional formatting.

The @ is to indicate Epydoc fields.

Semi-colon : is rst for sphinx (see either the Sphinx docs or the link above).

There's a related post here: What are these tags @ivar @param and @type in python docstring?

There may be other uses (possibly including Elixir, it's not a technology I'm familiar enough with to comment on).

Hope that helps.

Community
  • 1
  • 1
morric
  • 1,189
  • 1
  • 13
  • 17