Question

我最近开始在我的项目中添加文档，并且我尝试按照Google风格指南进行操作。我正在使用Sphinx生成文档和Sphinx扩展拿破仑，以弥合Google styleguide和reST之间的差距。

我在渲染params和Notes方面没有问题，但我似乎无法让Example部分呈现代码片段。

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

         Note:
             Chickens love to eat feed

         Example:
             chicken.eats(feed)
      """

我还尝试使用示例部分的双冒号。

Example::

Answer 1

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

所以，在你的例子中，试试这个：

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

         Note:
             Chickens love to eat feed

         Example::

             chicken.eats(feed)
      """

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

Google样式文档字符串示例部分不会呈现为代码段

2 个答案: