Search code examples
pythonpython-sphinxdocstringgoogle-style-guide

Python and sphinx: bullet point list in multiline google style docstring


I am currently documenting my Python project using Sphinx. I have come across an issue when including a bullet point list in the multi-line part of a docstring.

I would like to include a bulleted list, but one of the items is quite long. I would like to:

  • have the bullet list correctly rendered through Sphinx
  • but also have my code respecting PEP8 about line length (<79)

What would you advice for me to do for this docstring:

class geography():
""" Class defining a geography (cities and distance matrix)

This class implements a geography with a list of named cities with their
associated coordinates in a plane. Helper functions enable to :

- give a visual representation of that geography
- give a visual representation of the distance matrix
- give a visual representation of a configuration, a configuration being the repartition of some or all cities in pools

...

Last line is way over 79 characters.

Comments are then rendered through Sphinx. Adding a carriage return just breaks the bullet point list in Sphinx.


Solution

  • You can break the bulleted line as you like. Just line up the continuation with the previous lines text like:

    - give a visual representation of that geography
    - give a visual representation of the distance matrix
    - give a visual representation of a configuration, a configuration being the
      repartition of some or all cities in pools