Creating a literal text block in Sphinx

问题

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.

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.

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?

Example:

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

回答1:

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

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.

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)

Renders as shown in the image.

Rendered Docstring

回答2:

So this has never really happened to me before - I found the answer five minutes after posting. The magic of writing it out as a question in action!

The "literal" key word was essential. Apparently the way to avoid confusing the Sphinx parser is to use the "literal include" directive. So I saved my directory tree as a .txt and replaced the block in question with: .. literalinclude:: dir_tree.txt. Boom - nice looking green code box. Hopefully this saves some others tearing out their hair as I was.

来源：https://stackoverflow.com/questions/50937826/creating-a-literal-text-block-in-sphinx

标签

python

python-sphinx

restructuredtext