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
Answer from Stephen Rauch on Stack Overflow
Top answer
1 of 2
36

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
2 of 2
8

Solution from @Stephen Rauch was the perfect one. I just wanted to add that it also works for non bulleted lists. I had a similar issue with comments for arguments of functions or methods. For example:

def permute_array(arr, seq):
""" Function to "square permute" a 2D array

This function's purpose is to enable distance matrices permutations. That 
is, for example, permute both lines and columns of the array so as to 
reorder a distance matrix.

Args:
    arr (numpy array): the array to permute. It should be square of size n.
    seq (iterable of int): a permutation of range(n) (should be of length n and contain every integer from 0 to n-1)

Last line is way too long.

However, a "same indentation level" line break just breaks the nice sphinx method documentation:

    Args:
        arr (numpy array): the array to permute. It should be square of size n.
        seq (iterable of int): a permutation of range(n) (should be of length n
        and contain every integer from 0 to n-1)

Badly built documentation

But, breaking the line with an identation just works fine.

    Args:
        arr (numpy array): the array to permute. It should be square of size n.
        seq (iterable of int): a permutation of range(n) (should be of length n
            and contain every integer from 0 to n-1)

Nicely built documentation

🌐
GitHub
github.com › pawamoy › mkdocstrings › issues › 135
How to handle bullet list in python docstrings · Issue #135 · mkdocstrings/mkdocstrings
July 15, 2020 - def fn( x: tp.Union[ jnp.ndarray, np.ndarray, tp.Mapping[str, tp.Union[np.ndarray, jnp.ndarray]], tp.Tuple[tp.Union[np.ndarray, jnp.ndarray]], tp.Iterable, ] ): """ function Arguments: x: Input data. It could be - A Numpy or Jax array (or array-like), or a list of arrays - A dict mapping input names to the corresponding arrays, - A generator returning `(inputs,)`, `(inputs, targets)` """ Nonetheless, the documentation does not show it as a bullet list.
Author   charlielito
🌐
Softwareheritage
docs.softwareheritage.org › devel › contributing › sphinx.html
Sphinx gotchas — Software Heritage documentation
Here is a list of common gotchas when formatting Python docstrings for Sphinx and the Napoleon style. All sorts of lists require an empty line before the first bullet and after the last one, to be properly interpreted as list. No indentation is required for list elements w.r.t.
🌐
Matplotlib
matplotlib.org › sampledoc › cheatsheet.html
Sphinx cheat sheet — sampledoc 1.0 documentation
_making-a-list: Making a list ============= It is easy to make lists in rest Bullet points ------------- This is a subsection making bullet points * point A * point B * point C Enumerated points ------------------ This is a subsection making numbered points #. point A #. point B #. point C ..
🌐
Python
wiki.python.org › moin › HelpOnLists
HelpOnLists - Python Wiki
This is especially useful if your are discussing on a wiki page and want to have some kind of thread level that is viewable ... If you indent text like this, then it is indented in the output you can have multiple levels of indent ... For a simple unnumbered(bulleted) list use the asterisk * "*".
🌐
JetBrains
youtrack.jetbrains.com › issue › PY-51849 › Docstrings-Numbered-lists-not-shown-properly-after-multi-line-documentation.
Docstrings: Numbered lists not shown properly after multi- ...
{{ (>_<) }} This version of your browser is not supported. Try upgrading to the latest stable version. Something went seriously wrong
🌐
Readthedocs
clize.readthedocs.io › en › stable › docstring-reference.html
Customizing the help using the docstring — clize 5.0.2 documentation
Parameters are documented using the field list syntax: from clize import run def func(one, and_two): """ :param one: This documents the parameter called one. :param and_two: Documentation for the 'and_two' parameter. It may continue on a second line. """ run(func) Begin a line with :param NAME: and continue with a description for the parameter. You can continue over more lines by indenting the additional lines. $ python docstring...
🌐
Stack Overflow
stackoverflow.com › questions › 68107312 › how-do-put-a-bullet-list-in-docstring-for-raises
python - How do put a bullet list in docstring for 'Raises'? - Stack Overflow
June 23, 2021 - I don't think the NumPy (or Google) style supports bullet lists in docstring sections such as Raises. You can have a single paragraph of plain text.
Find elsewhere
🌐
GitHub
github.com › mkdocstrings › mkdocstrings › issues › 486
Indention within bullet list · Issue #486 · mkdocstrings/mkdocstrings
October 16, 2022 - def docstest(int_val: int, float_val: float) -> float: """Function to showcase docstring problems. This docstring demnonstrates some issues using ``mkdocstrings`` with respect to the indention of text within a bullet list. Parameters ---------- int_val Integer value.
Author   andreas-vester
🌐
Sphinx
sphinx-doc.org › en › master › usage › restructuredtext › basics.html
reStructuredText Primer — Sphinx documentation
However, this convention is used in Python Developer’s Guide for documenting which you may follow: ... Of course, you are free to use your own marker characters (see the reStructuredText documentation), and use a deeper nesting level, but keep in mind that most target formats (HTML, LaTeX) have a limited supported nesting depth. Field lists (ref) are sequences of fields marked up like this:
🌐
Readthedocs
sphinx-rtd-theme.readthedocs.io › en › stable › demo › lists_tables.html
4. Lists & Tables — Read the Docs Sphinx Theme 3.1.0 documentation
Nested bullet list. Nested item 2. Third level. ... Nested item 3. ... This item has multiple paragraphs. This item has multiple paragraphs. This item has multiple paragraphs. This item has multiple paragraphs. ... 1# -*- coding: utf-8 -*- 2"""Test Module for sphinx_rtd_theme.""" 3 4 5class Foo: 6 7 """Docstring ...
🌐
JetBrains
youtrack.jetbrains.com › issue › PY-61216 › Bullet-point-lists-in-docstrings-not-rendered-properly
Bullet point lists in docstrings not rendered properly
{{ (>_<) }} This version of your browser is not supported. Try upgrading to the latest stable version. Something went seriously wrong
🌐
SourceForge
epydoc.sourceforge.net › manual-epytext.html
The Epytext Markup Language - Epydoc
If the first contained block is ... from the bullet by one or more spaces, as shown in the previous example. All other block types must follow on separate lines. Every list must be separated from surrounding blocks by indentation: Note that sublists must be separated from the blocks in their parent list item by indentation. In particular, the following docstring generates ...
🌐
Readthedocs
sphinxcontrib-napoleon.readthedocs.io › en › latest › example_google.html
Example Google Style Python Docstrings — napoleon 0.7 documentation
The __init__ method may be documented in either the class level docstring, or as a docstring on the __init__ method itself. Either form is acceptable, but the two should not be mixed. Choose one convention to document the __init__ method and be consistent with it. Note: Do not include the `self` parameter in the ``Args`` section. Args: param1 (str): Description of `param1`. param2 (:obj:`int`, optional): Description of `param2`. Multiple lines are supported. param3 (:obj:`list` of :obj:`str`): Description of `param3`. """ self.attr1 = param1 self.attr2 = param2 self.attr3 = param3 #: Doc comme
🌐
Readthedocs
alf.readthedocs.io › en › latest › notes › howto_docstring.html
How to write docstrings (or RST files) - Agent Learning Framework (ALF) documentation
For example, the two docstrings below · class Algorithm(object): """An algorithm base class.""" def __init__(self, observation_spec, action_spec): """The init function of Algorithm. """ will be combined into one description of the class constructor: An algorithm base class. The init function of Algorithm. So try to avoid duplicate sentences at the two places. The argument list should always starts with a string “Args:” with a line break, after which the arguments will be listed and explained:
🌐
Pyansys
dev.docs.pyansys.com › doc-style › docstrings.html
Numpydoc docstrings — PyAnsys developer's guide
Ensure that there are no blank ... signifies the start of a new paragraph. To create a bulleted or numbered list, ensure that there is a blank line before the first item and after the last item....
🌐
Docutils
docutils.sourceforge.io › docs › ref › rst › restructuredtext.html
reStructuredText Markup Specification - Docutils - SourceForge
.. _Python DOC-SIG mailing list archive: .. _archive: .. _Doc-SIG: https://mail.python.org/pipermail/doc-sig/ An inline form of internal hyperlink target is available; see Inline Internal Targets. ... Works also, if the internal hyperlink target is "nested" at the end of an indented text block. This behaviour allows setting targets to individual list items (except the first, as a preceding internal target applies to the list as a whole): * bullet list ..
🌐
Lsst
developer.lsst.io › python › numpydoc.html
Documenting Python APIs with docstrings — LSST DM Developer Guide main documentation
This module demonstrates documentation written according to LSST DM's guidelines for `Documenting Python APIs with Docstrings`_. Notes ----- Docstrings have well-specified sections. This is the Notes section. Permitted sections are listed in `Numpydoc Sections in Docstrings`_.