<div dir="ltr"><div>Let's summarize the facts mentioned in the thread to continue discussion:</div><div>**1.** ".. zuul:rolevar::" structure is used to generate a documentation so using a different syntax is not an option</div><div><br></div><div>**2.** turn rendering of rst files off:</div><div>**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 <a href="http://opendev.org">opendev.org</a> over <a href="http://github.com">github.com</a><br></div><div><br></div><div>**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.</div><div><br></div><div>[5] <a href="https://opendev.org/openstack/tempest">https://opendev.org/openstack/tempest</a></div><div>[6] <a href="https://opendev.org/openstack/tempest/src/branch/master/README.rst">https://opendev.org/openstack/tempest/src/branch/master/README.rst</a></div><div>[7] <a href="https://review.opendev.org/#/c/747796/">https://review.opendev.org/#/c/747796/</a></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Tue, 25 Aug 2020 at 16:22, Brian Rosmaita <<a href="mailto:rosmaita.fossdev@gmail.com" target="_blank">rosmaita.fossdev@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">On 8/24/20 11:05 AM, Clark Boylan wrote:<br>
> On Mon, Aug 24, 2020, at 7:36 AM, Jeremy Stanley wrote:<br>
>> On 2020-08-24 16:12:17 +0200 (+0200), Martin Kopec wrote:<br>
>>> I've noticed that READMEs of zuul roles within openstack projects<br>
>>> are not rendered properly on <a href="http://opendev.org" rel="noreferrer" target="_blank">opendev.org</a> - ".. zuul:rolevar::"<br>
>>> syntax seems to be the problem. Although it's rendered well on<br>
>>> <a href="http://github.com" rel="noreferrer" target="_blank">github.com</a>, see f.e. [1] [2].<br>
<br>
[snip]<br>
<br>
>> To be entirely honest, I wish Gitea didn't automatically attempt to<br>
>> render RST files, that makes it harder to actually refer to the<br>
>> source code for them, and it's a source code browser not a CMS for<br>
>> publishing documentation, but apparently this is a feature many<br>
>> other users do like for some reason.<br>
> <br>
> We can change this behavior by removing the external renderer (though I expect we're in the minority of preferring ability to link to the source here).<br>
<br>
This may be a bigger minority that you think ... I put up a patch to <br>
change the default behavior to not render RST, so anyone with a strong <br>
opinion, please comment on the patch:<br>
   <a href="https://review.opendev.org/#/c/747796/" rel="noreferrer" target="_blank">https://review.opendev.org/#/c/747796/</a><br>
<br>
> <br>
> [3] <a href="https://opendev.org/opendev/system-config/src/branch/master/playbooks/roles/gitea/templates/app.ini.j2#L88-L95" rel="noreferrer" target="_blank">https://opendev.org/opendev/system-config/src/branch/master/playbooks/roles/gitea/templates/app.ini.j2#L88-L95</a><br>
> [4] <a href="https://opendev.org/opendev/system-config/src/branch/master/docker/gitea/Dockerfile#L92-L94" rel="noreferrer" target="_blank">https://opendev.org/opendev/system-config/src/branch/master/docker/gitea/Dockerfile#L92-L94</a><br>
> <br>
>> -- <br>
>> Jeremy Stanley<br>
> <br>
<br>
<br>
</blockquote></div>