Let's summarize the facts mentioned in the thread to continue discussion:
**1.** ".. zuul:rolevar::" structure is used to generate a documentation so using a different syntax is not an option
**2.** turn rendering of rst files off:
**2a:** in order to make pointing to the source code easier - that's an interesting topic, probably it would be better to discuss this separately - turning rendering completely off would be a step back from the visual perspective, however, I can imagine that referring to the specific lines of rst files can be needed in some cases. The automatic rst rendering is really useful, f.e when I open a repo I really appreciate that README.rst is rendered under the list of files (f.e. this view [5]). On the other side, when I open specifically a rst file (f.e. this view [6]) I can totally imagine that this file would be opened in a mode when a user can refer to any line like it is with any other source file. If not that, what about adding a new button besides Raw, Permalink, Blame, History called f.e. Source? This functionality would give a certain advantage to
opendev.org over
github.com
**2b:** in order to avoid omitting content - as also mentioned in the comments in [7] turning rendering completely off would be a step back at least from the visual perspective, therefore I'd rather move to the direction where we improved rendering capabilities - either switching to a different rendering tool or just implementing some kind of try except block as Jeremy suggested in [7] - if rendering of a certain block of code throws an error, that part of the code would be rendered as is.