Google style docstring Example section is not rendering as a code snippet

Question

I recently started adding documentation to my project and I'm trying to follow the Google style guide. I am using Sphinx to generate the documents and the Sphinx extension napoleon to bridge the gap between the Google styleguide and reST.

I have no problem rendering params and Notes but I can't seem to get the Example section to render a code snippet.

class Chicken(object):
      """Animal that lays egg and has feathers

         Note:
             Chickens love to eat feed

         Example:
             chicken.eats(feed)
      """

I have also tried a double colon with the Example section.

Example::

Hebraism

Answer 1

You need a double colon AND a blank line between the Example:: section break and the literal block.

See the example from the Napoleon docs:

"""Example Google style docstrings.

This module demonstrates documentation as specified by the `Google Python
Style Guide`_. Docstrings may extend over multiple lines. Sections are created
with a section header and a colon followed by a block of indented text.

Example:
    Examples can be given using either the ``Example`` or ``Examples``
    sections. Sections support any reStructuredText formatting, including
    literal blocks::

        $ python example_google.py

Section breaks are created by resuming unindented text. Section breaks
are also implicitly created anytime a new section starts.
"""

So, in your example, try this:

class Chicken(object):
      """Animal that lays egg and has feathers

         Note:
             Chickens love to eat feed

         Example::

             chicken.eats(feed)
      """

Mini

While the example successfully creates a code block, the text for "Example" is not rendered the same (presumably not as a section break). With "Example:" followed by indented text, ending in "::" and a code block, "Example" is bolded in output. With "Example::" followed by a code block, "Example" is not bolded in output. – Harlen

Answer 2

Building off the answer by @Brown, it appears in order to get the Example section to render as both a recognized section break and as a code snippet you would use "Example:" followed by an indented "::" followed by a blank line and a double-indented code snippet. For me, both of the following introduce a code block beginning with a bolded "Example" in the output.

class Chicken(object):
      """Animal that lays egg and has feathers

         Note:
             Chickens love to eat feed

         Example:
             Detail about example (I'm feeding the chicken)::

                 chicken.eats(feed)
      """

OR:

class Chicken(object):
      """Animal that lays egg and has feathers

         Note:
             Chickens love to eat feed

         Example:
             ::

                 chicken.eats(feed)
      """

Harlen