Python 在Sphinx中创建文字文本块

我想在docstring中创建一个目录树，并在不更改Sphinx文档的情况下呈现它，但我遇到了麻烦。我试过使用：单回、双回和三回刻度；文字

：代码：

；和literal

。。代码块：：python

来实现这一点。我认为后两种方法不起作用，因为这个块也是无效的Python/代码。此外，我还改变了压痕的数量和类型以及间距，但都无济于事

下面是我的示例（使用三个背面记号来描绘所讨论的块）。因此，我的问题是-如何准确地将docstring中的块渲染为Sphinx，如docstring中所示？我基本上想暂时关闭标记，并像在文本文件中一样显示管道和缩进

为了充分披露，我确实发现，但在他们提出要求时，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

---

所以这在我身上从未发生过——我在发帖五分钟后找到了答案。把它写成一个实际问题的魔力

---

“文字”关键词至关重要。显然，避免混淆Sphinx解析器的方法是使用。因此，我将目录树保存为.txt，并将有问题的块替换为：

。。literalinclude:：dir_tree.txt

。繁荣-好看的绿色代码框。希望这能避免其他人像我一样扯掉头发

空白在重构文本中有意义。缩进和新行可能很棘手，尤其是使用

代码块时

还要注意的是，在StructuredText中，单个反标记以斜体显示，而不是内联代码，而在Markdown中，它们以内联代码显示。对于reStructuredText，使用双反勾号渲染内联代码示例

最后，请注意，应使用第一个docstring分隔符
“”“
”来设置第一个缩进。您的示例具有0-空格缩进，然后是4-空格缩进。最好将docstring分隔符放在单独的行上，以便缩进显示一致

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)

如图所示进行渲染

步骤1：使用
编写正确显示代码的有效重构文本。代码块：：文本
而不是默认的
：
后跟两行空行（默认情况下，这将被解释为Python代码）。第2步，将重构文本复制粘贴到您的docstring中，同时确保正确的空格和缩进。对于示例树，请注意，我使用的Unicode字符需要进一步的Sphinx配置，但您可以看到它是如何工作的。@StevePiercy感谢您的建议，尽管我无法使其工作。我复制粘贴了您的text（不在页面的“原始”视图中），将unicode替换为管道和破折号。由于缩进，它在第一行之后中断。也许unicode不会中断它？（我不太熟悉这一点-我想我甚至不知道间距是否实际上是unicode而不是制表符？）如果您发布了一个基于我文章的示例的答案，我可能会接受。我更喜欢在源代码和文档中保留目录结构作为可视化的解决方案-显然我的解决方案不使用git，您可以找到以前的非Unicode版本，否则请使用文档更新您的问题您在测试中使用的字符串。我发现您当前的版本有一个问题，第一行没有缩进
“设置临时文件夹”
，后面的所有内容都缩进，直到它到达
属性。我觉得这很奇怪。泛型文字块只是一个缩进的块，前面有一个以
：
结尾的段落。请参阅。@mzjn感谢您的评论和参考。不幸的是，我以前也试过（我忘记了所有我试过的东西，因为我已经试了几个小时了，所以忘了列出这个）。这种方法的问题是，它在第一行之后会因为多重缩进而中断，这是我真正想要保留的元素