python sphinx - How to include an internal reference in a code block?

Question

In my Sphinx .rst document I have a code block containing a tree view of the structure of my product using the UNIX tree command:

  |── parent
  |?? |── child
  |??     |── grandchild

It's in a code block so that Sphinx preserves the whitespaces.

I want readers to be able to click on each node to follow an internal hyperlink to the part of the document that describes that node. However, adding a :ref: inside the code block doesn't work (see below). Does anyone know how to achieve this?

This doesn't work:

.. _parent:

Parent
------
Blah blah

.. _child:

Child
-----
Blah blah

.. _grandchild:

Grandchild
----------
Blah blah

Then...:

|── :ref:`parent`
|   |── :ref:`child`
|       |── :ref:`grandchild`

Answer 1

You can use the parsed-literal directive:

.. parsed-literal:: 

   |── :ref:`parent`
   |   |── :ref:`child`
   |       |── :ref:`grandchild`

This works, but there are warning messages saying "WARNING: Inline substitution_reference start-string without end-string."

The vertical bars are interpreted as parts of substitution references. The warnings go away with some escaping:

.. parsed-literal:: 

   |── :ref:`parent`
   |   |── :ref:`child`
   |       |── :ref:`grandchild`