Sphinx 自动文档和多行字符串

Question

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

\n\n

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

\n\n

这可能吗？

\n\n

mymodule.py

\n\n

#: Default configuration\nDEFAULT_CONFIG = r"""\n{ "foo": "bar",\n  "baz": "rex" }\n"""\n

\n\n

mydocs.rst

\n\n

...\n\n--------------\nDefault Config\n--------------\n\n.. autodata:: mymodule.DEFAULT_CONFIG\n

\n\n

生成的 Sphinx 文档

\n\n

mymodule.DEFAULT_CONFIG\n= "{ \\"foo\\": \\"bar\\",\\n  \\"bar\\": \\"rex\\" }"\n\nstr(object=\xe2\x80\x99\xe2\x80\x98) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str\n\nCreate a new string object from the given object.\nIf encoding or errors is specified, then the object\nmust expose a data buffer that will be decoded using\nthe given encoding and error handler. Otherwise, returns\nthe result of object.__str__() (if defined) or repr(object).\nencoding defaults to sys.getdefaultencoding(). errors defaults to \xe2\x80\x98strict\xe2\x80\x99.\n

\n\n

所需的 Sphinx 文档

\n\n

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

\n

Answer 1

这不能直接支持，但由于您使用的是 Sphinx 和 Python，所以我决定采用以下 hack：

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

2. 这个 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文档并确保其有效:)