Sphinx autodoc和多行字符串

Question

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

下面是一些示例Python代码，RST以及它如何使用Number is 999 -> result is 999 (expected) Number is 2532 -> result is 2.5k (expected) Number is 10000 -> result is 97k (not expected) Number is 100000 -> result is 145k (not expected) 呈现。但是，我宁愿得到像“希望的狮身人面像文档”这样的东西。

这可能吗？

mymodule.py

sphinx-build

mydocs.rst

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

生成的Sphinx文档

...

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

Answer 1

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

1. 在此示例中，您可以import您想要的变量。这应该已经有效，因为autodoc能够产生输出。

2. 这个hack会让你有一个更人性化的输出，但你还仍然有变量的值（就狮身人面像而言）在不受欢迎的情况下（有一堆\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``.
'''

在您的狮身人面像文档中

在上面有autodata的任何文件中（我使用automodule，都没关系）。文档看起来像这样（很明显，你已经有了这个，不需要改变它）。您需要更改的是您的实际python文档字符串，以及下一节。这是为了完整答案。

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

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

修改您的conf.py

这是一个奇特的部分，使用Sphinx的巨大好处 - Python在编写文件时非常方便。在上面的docstring中，您会看到我故意拥有.. 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版本。我们只是把它放在docstring中。 两者非常有用。原因是因为使用.. code-block:: py方法，Sphinx将删除前导/尾随换行符（因此文档字符串中的.. note::）。因此，拥有人类可读的版本非常有用，但了解原始值也很有用。

唯一值得一提的是天空是极限！我选择使用.. code-block:: py作为我的目的，但由于你自己编写文件，你可以做任何你想做的事情。您可以编写该文件，以便生成

.. code-block:: py

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

更改conf.py中的部分。它取决于你！更改输出时可能会出现错误，打开生成的.rst文档并确保其有效：）