Creating a literal text block in Sphinx

Question

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

A generic literal block is simply an indented block that is preceded by a paragraph that ends with ::. See sphinx-doc.org/en/master/usage/restructuredtext/…. — mzjn
@mzjn Thanks for your comment and the reference. Unfortunately I have tried that before (I lost track of all the things I tried because I was at it for hours, so forgot to list this one). The problem with this method is it breaks after the first line because of the multiple indenting - which was an element I really wanted to retain — HFBrowning

Steve Piercy Steve Piercy · Accepted Answer · 2018-06-20T20:50:53

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

Creating a literal text block in Sphinx

2 Answers