Python Sphinx: How to embed code into a docstring?

Question

How can I embed code into a docstring to tell Sphinx to format the code similar as it will be done in Markdown (different background colour, monospaced sans font)? For example to document a code usage example.

""" This is a module documentation

Use this module like this:

   res = aFunction(something, goes, in)
   print(res.avalue)

"""

Answer 1

There are a few ways to do it . I think the most sensible in your case would be .. code-block::

""" This is a module documentation

Use this module like this:

.. code-block:: python

   res = aFunction(something, goes, in)
   print(res.avalue)

"""

Notice the blank line between the directive and the code block - it must be there in order for the block to render properly.

Answer 2

Another way ( see the comment of mzjn on this post ) to get code highlighted is to end with two(!) colons at the line before the code:

""" This is a module documentation

Use this module like this::

   res = aFunction(something, goes, in)
   print(res.avalue)

"""

The :: does the trick.