谷歌风格的文档字符串示例部分未呈现为代码片段。

Question

我最近开始为我的项目添加文档，并尝试遵循Google风格指南。我正在使用Sphinx生成文档，并使用Sphinx扩展napoleon来弥补Google风格指南和reST之间的差距。

我可以轻松地呈现params和Notes，但是似乎无法使示例部分呈现代码片段。

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

         Note:
             Chickens love to eat feed

         Example:
             chicken.eats(feed)
      """

我也尝试过在示例部分使用双冒号。

Example::

- Crystal

Answer 1

在Example::节之间需要一个双冒号和一个空行，这与文本块不同。

请参阅Napoleon文档中的示例：

"""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.
"""

所以，在您的示例中，请尝试这样做：

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

         Note:
             Chickens love to eat feed

         Example::

             chicken.eats(feed)
      """

- Brown

---

虽然示例成功创建了一个代码块，但“Example”的文本并没有呈现出相同的效果（可能不是作为分节符）。使用“Example:”后跟缩进的文本，以“::”结尾和一个代码块，“Example”在输出中会加粗。使用“Example::”后跟一个代码块，“Example”在输出中不会加粗。 - Dan

Answer 2

建立在@Brown的答案之上，为了使示例部分既能作为一个被认可的部分分隔符又能作为代码片段呈现，您需要使用"Example:"，然后是一个缩进的"::"，接着是一个空行和一个双倍缩进的代码片段。对我来说，下面两个都会在输出中引入以粗体“Example”开头的代码块。

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)
      """

- Dan