在 Sphinx 中创建文字文本块

Question

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

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

为了全面披露，我确实找到了，但在他们询问时，OP 似乎已经放弃了 Sphinx，post 是 2015 年的，他们有不同的约束（leading/trailing 空行，相对于缩进和管道）。认为没有办法做到这一点对我来说很疯狂吗？

示例：

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

所以我以前从未真正遇到过这种情况 - 我在发帖五分钟后找到了答案。把它写成一个问题的魔力在行动！

"literal" 关键字是必不可少的。显然，避免混淆 Sphinx 解析器的方法是使用 "literal include" directive。所以我将我的目录树保存为 .txt 并将有问题的块替换为：.. literalinclude:: dir_tree.txt。 Boom - 漂亮的绿色代码框。希望这可以避免其他人像我一样撕掉他们的头发。

Answer 2

Whitespace 在 reStructuredText 中有意义。缩进和换行可能很棘手，尤其是 code-block.

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

最后注意第一个docstring定界符"""要设置第一个缩进。您的示例有 0-space 缩进，后跟 4-space 缩进。最好将文档字符串定界符放在不同的行上，以便缩进始终如一。

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)

呈现如图所示。

在 Sphinx 中创建文字文本块

Creating a literal text block in Sphinx

python

restructuredtext

python-sphinx