在 Sphinx 中创建文字文本块

Question

我想在文档字符串中创建一个目录树，并在不更改我的 Sphinx 文档的情况下呈现它，但我遇到了麻烦。我尝试过使用：单反引号、双反引号和三反引号；字面意思:code:；并字面意思.. code-block:: python让它发挥作用。我想后两者不起作用，因为这个块也不是有效的 Python/代码。此外，我还改变了缩进和间距的数量和类型，但没有效果。

我的示例（使用三个反引号来描绘有问题的块）如下。因此我的问题是 - 如何将文档字符串中的块完全按照文档字符串中所示的方式渲染到 Sphinx？我基本上想暂时关闭标记并像在文本文件中一样显示管道和缩进。

为了充分披露，我确实找到了这种相关的帖子，但似乎 OP 在他们询问时已经放弃了 Sphinx，该帖子是 2015 年的，并且他们有不同的限制（前导/尾随空白行，与缩进和管道相比）。我觉得没有办法做到这一点真是太疯狂了？

例子：

class SetUp(object)
    """Set up temp folders, log files, and global variables.

    The folder tree for setting up looks as follows (using attached
    attribute names rather than paths):

    ```
    |-- workspace
        |-- folder_name (all up to this point = work_folder)
            |-- proc_id (^= process_path)
                |-- gdb_name.gdb (^= gdb_full_path)
    ```

    Using `^=` as short-hand for `'all up to this point, os.path.join()`.

    Attributes
    ----------
    (Etc)
    """
    def __init__(self, log_level, proc_id, gdb_name):
        self.folder_name = "CHECKLIST"
        self.proc_id = proc_id
        # Etc

Answer 1

空格在 reStructuredText 中有意义。缩进和新行可能很棘手，尤其是对于code-block.

另请注意，在 reStructuredText 中，单个反引号呈现为斜体，而不是内联代码，而在 Markdown 和 SO 中，它们确实呈现为内联代码。对于 reStructuredText，使用双反引号来呈现内联代码示例。

最后，请注意第一个文档字符串分隔符"""应用于设置第一个缩进。您的示例有 0 个空格缩进，后跟 4 个空格缩进。最好将文档字符串分隔符放在单独的行上，以便缩进显示一致。

Set up temp folders, log files, and global variables.

The folder tree for setting up looks as follows (using attached attribute
names rather than paths):

.. code-block:: text

    |-- workspace
        |-- folder_name (all up to this point = work_folder)
            |-- proc_id (^= process_path)
                |-- gdb_name.gdb (^= gdb_full_path)

Using ``^=`` as short-hand for ``'all up to this point, os.path.join()``.

Attributes
==========
(Etc)

渲染如图所示。