python - 在 Sphinx 中创建文字文本 block

Question

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

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

为了充分披露，我确实找到了 this kind-of related post但看起来 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)

渲染如图所示。