在 Sphinx 中创建文字文本块 [英] Creating a literal text block in Sphinx

问题描述

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

I would like to make a directory tree in a docstring and have it rendered without change to my Sphinx documentation, but I am having trouble. I have tried using: single, double, and triple back-ticks; literal :code:; and literal .. code-block:: python to get this to work. I imagine the latter two did not work because this block is also not valid Python/code. In addition I have varied the number and type of indentation and spacing, to no avail.

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

My example (using three back-ticks to delineate the block in question) is below. Therefore my question is - how does one render a block from a docstring to Sphinx exactly as shown in the docstring? I basically want to turn off the markup for a moment and present the pipes and indents as I would in a text file.

为了充分披露，我确实找到了 这种相关的帖子 但看起来 OP 在他们提出要求时已经放弃了 Sphinx，该帖子是 2015 年的，并且他们有不同的限制(前导/尾随空白行，与缩进和管道).认为没有办法做到这一点对我来说是疯狂的吗?

In the interest of full disclosure, I did find this kind-of related post but it appears the OP had already given up on Sphinx by the time they asked, the post is from 2015, and they had different constraints (leading/trailing blank lines, versus indents and pipes). It's crazy to me to think that there wouldn't be a way to do this?

示例:

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

推荐答案

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

Whitespace has meaning in reStructuredText. Indents and new lines may be tricky, especially with code-block.

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

Also note that single backticks render as italics, not inline code, in reStructuredText, whereas in Markdown and SO they do render as inline code. For reStructuredText use double backticks to render inline code samples.

最后，注意第一个文档字符串分隔符"""应该用于设置第一个缩进.你的例子有0个空格缩进，后面是4个空格缩进.最好是将您的文档字符串分隔符放在单独的行上，以便缩进一致.

Finally, pay attention that the first docstring delimiter """ should be used to set the first indent. Your example has 0-space indent, followed by 4-space indent. It is better to have your docstring delimiters on separate lines so that indentation appears consistently.

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 中创建文字文本块的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！