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 http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#literal-blocks. — mzjn, Jun 20 '18 at 07:23
@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, Jun 20 '18 at 15:27

score 12 · Accepted Answer · answered Jun 20 '18 at 20:50

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

score 2 · Answer 2 · answered Jun 19 '18 at 22:54

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.

answered Jun 19 '18 at 22:54

HFBrowning

2,196
3
23
42

Step 1: write valid reStructuredText that displays code correctly using `.. code-block:: text` instead of the default `:` followed by two blank lines (this gets interpreted as Python code by default). Step 2, copy-paste the reStructuredText into your docstring while ensuring proper whitespace and indentation. For an example tree, see https://github.com/Pylons/pyramid/blame/master/docs/quick_tutorial/tutorial_approach.rst#L23-L33 Note that I used Unicode characters that required further Sphinx configuration, but you can see how it works. – Steve Piercy Jun 19 '18 at 23:38
@StevePiercy Thanks for your suggestion though I wasn't able to get it to work. I copy-pasted your text (out of the "raw" view of your page), replacing unicode with pipes and dashes. It broke after the first line because of indenting. Perhaps unicode would not have broken it? (Something I'm not very familiar with - I suppose I don't even know if the spacing is actually unicode rather than tabs?) – HFBrowning Jun 20 '18 at 15:40
If you posted an answer with an example based off my post, I would probably accept it. I *would* prefer a solution that retains the directory structure as a visual both in the source and in the docs - which obviously my solution does not – HFBrowning Jun 20 '18 at 15:42
Using git blame, one can find the previous non-Unicode version https://github.com/Pylons/pyramid/blame/54a21885712c6daf367393a0a9d788c2688c48cd/docs/quick_tutorial/tutorial_approach.rst#L20-L33 Otherwise please update your question with the docstring you use in testing. I see your current version has a problem where the first line has no indent `"""Set up temp folders` followed by everything else indented until it hits `Attributes`. It looks odd to me. – Steve Piercy Jun 20 '18 at 20:38

Creating a literal text block in Sphinx

2 Answers2

Linked