python - Sphinx autodoc 和多行字符串

Question

我有一个 python 模块，它定义了一个多行字符串常量。我想在基于 Sphinx 的文档中很好地显示多行字符串。

下面是一些 Python 代码示例，RST 以及它如何使用 sphinx-build 呈现.但是，我宁愿得到类似“所需的狮身人面像文档”之类的东西。

这可能吗？

我的模块.py

#: Default configuration
DEFAULT_CONFIG = r"""
{ "foo": "bar",
  "baz": "rex" }
"""

mydocs.rst

...

--------------
Default Config
--------------

.. autodata:: mymodule.DEFAULT_CONFIG

生成的 Sphinx 文档

mymodule.DEFAULT_CONFIG
= "{ \"foo\": \"bar\",\n  \"bar\": \"rex\" }"

str(object=’‘) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object.
If encoding or errors is specified, then the object
must expose a data buffer that will be decoded using
the given encoding and error handler. Otherwise, returns
the result of object.__str__() (if defined) or repr(object).
encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

所需的 Sphinx 文档

mymodule.DEFAULT_CONFIG = Default configuration
{ "foo": "bar",
  "baz": "rex" }

Answer 1

这不能直接得到支持，但由于您使用的是 Sphinx 和 Python，因此我决定采用以下 hack:

在此示例中，重要的是您可以 import你想要的变量。这应该已经工作了，因为 autodoc能够产生输出。

此 hack 将使您获得更人性化的输出，但是 你会还有变量的值(就 sphinx 而言)仍然是不受欢迎的(带有一堆 \n 字符)。

我将为此重用我自己的项目，但使用您的变量/值。我的包名是 exhale我放入的文件是 exhale/configs.py ，所以这就是那些东西的来源。所以这是布局:

文件: exhale/configs.py
这是您的实际 python 代码。它看起来像这样:

__name__ = "configs"
__docformat__ = "reStructuredText"

DEFAULT_CONFIG = r"""
{ "foo": "bar",
  "baz": "rex" }
"""
'''
This is some description of the use of / intended purpose of the variable.

The contents of this variable are a multi-line string with value:

.. include:: DEFAULT_CONFIG_value.rst

.. note::

   The above value is presented for readability, take special care in use of
   this variable that the real value has both a leading and trailing ``\\n``.
'''

在您的 sphinx 文档中

在您拥有 autodata 的任何文件中上面(我用过 automodule ，没关系)。文档看起来像这样(要清楚，你已经得到了这个， 不需要更改它 )。您需要更改的是您的实际 python 文档字符串和下一部分。这是为了完整的答案。

Exhale Configs Module
=====================

.. automodule:: exhale.configs
   :members:
   :undoc-members:

修改您的 conf.py
这是花哨的部分，也是使用 Sphinx 的一个巨大好处——Python 在编写文件时非常方便。在上面的文档字符串中，你会看到我故意有一个 .. include指示。疯狂的部分是我们可以动态地编写这个文件。在您的 conf.py 底部，你可以添加类似的东西

# Import the variable from wherever it lives
from exhale.configs import DEFAULT_CONFIG
default_parts = DEFAULT_CONFIG.strip().splitlines()
# Because I am deliberately putting this underneath a '.. code-block:: py',
# we need to indent by **THREE** spaces.
#
# Similarly, when writing to the file, the "\n\n   " before
# {default_config_value} (the three spaces) is also important ;)
default_config_value = "\n   ".join(p for p in default_parts)
with open("DEFAULT_CONFIG_value.rst", "w") as dcv:
    dcv.write(".. code-block:: py\n\n   {default_config_value}\n\n".format(
        default_config_value=default_config_value
    ))

如果您使用 Python 3 ，而不是拆分和连接，只需使用 textwrap.indent .我这样做只是为了确保 Python 2 用户可以复制。

卡布姆

当你运行 make html ，它将重新生成文件 DEFAULT_CONFIG_value.rst每次!因此，即使您更改了变量的值，也应该很好。作为引用，为我生成的文件如下所示

.. code-block:: py

   { "foo": "bar",
     "baz": "rex" }

备注 : 这不是一个独立的 reStructuredText 文档，它只能通过 .. include:: 使用。 !

最后但并非最不重要的一点是，渲染的输出如下所示:



如序言所述，Sphinx 是 将包括 \n值中的版本。我们只是把它放在文档字符串中。拥有 非常有用两个 .原因是因为 .. code-block:: py方法，Sphinx 将去除前导/尾随换行符(因此 .. note:: 在文档字符串中)。因此，拥有人类可读的版本非常有帮助，但了解原始值也很有用。

这里唯一值得一提的是，天空才是极限!我选择使用 .. code-block:: py出于我的目的，但是由于您实际上是自己编写文件，因此您可以做任何您想做的事情。您可以编写文件，以便它生成

.. code-block:: py

   DEFAULT_CONFIG = r"""
   { "foo": "bar",
     "baz": "rex" }
   """

通过更改 conf.py 中的部分.由你决定!更改输出时可能会出现错误，请打开生成的 .rst记录并确保其有效:)