Sphinx autodoc 和多行字符串

Question

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

下面是一些示例 Python 代码、RST 以及它如何使用 sphinx-build 呈现。但是，我宁愿得到像 "desired sphinx docs".

这样的东西

这可能吗？

mymodule.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 我决定采用以下技巧：

在此示例中，重要的是您可以 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 个用户可以复制。

KABOOM

当你运行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 文档并确保其有效 :)

Sphinx autodoc 和多行字符串

Sphinx autodoc and multi-line strings

python

python-sphinx

autodoc

文件：`exhale/configs.py`

在您的 sphinx 文档中

修改你的`conf.py`

KABOOM

Sphinx autodoc 和多行字符串

Sphinx autodoc and multi-line strings

python

python-sphinx

autodoc

文件：exhale/configs.py

在您的 sphinx 文档中

修改你的conf.py

KABOOM

文件：`exhale/configs.py`

修改你的`conf.py`