在Sphinx中创建文字文本块

Question

我想在文档字符串中创建目录树，并使其呈现为而无需更改，但是我遇到了麻烦。我试过使用：单，双和三反引号；文字: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

所以这从来没有真正发生过-在发布五分钟后我找到了答案。将其写成实际问题的神奇之处！

“文字”关键字至关重要。显然，避免混淆Sphinx解析器的方法是使用"literal include" directive。因此，我将目录树另存为.txt，并将有问题的块替换为：.. literalinclude:: dir_tree.txt。繁荣-漂亮的绿色代码框。希望这可以节省一些其他人像我一样撕头发。

Answer 2

空白在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)

如图所示渲染。