Open Stack

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.

[5] https://opendev.org/openstack/tempest
[6] https://opendev.org/openstack/tempest/src/branch/master/README.rst
[7] https://review.opendev.org/#/c/747796/

On Tue, 25 Aug 2020 at 16:22, Brian Rosmaita <rosmaita.fossdev at gmail.com>
wrote:

> On 8/24/20 11:05 AM, Clark Boylan wrote:
> > On Mon, Aug 24, 2020, at 7:36 AM, Jeremy Stanley wrote:
> >> On 2020-08-24 16:12:17 +0200 (+0200), Martin Kopec wrote:
> >>> I've noticed that READMEs of zuul roles within openstack projects
> >>> are not rendered properly on opendev.org - ".. zuul:rolevar::"
> >>> syntax seems to be the problem. Although it's rendered well on
> >>> github.com, see f.e. [1] [2].
>
> [snip]
>
> >> To be entirely honest, I wish Gitea didn't automatically attempt to
> >> render RST files, that makes it harder to actually refer to the
> >> source code for them, and it's a source code browser not a CMS for
> >> publishing documentation, but apparently this is a feature many
> >> other users do like for some reason.
> >
> > 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).
>
> This may be a bigger minority that you think ... I put up a patch to
> change the default behavior to not render RST, so anyone with a strong
> opinion, please comment on the patch:
>    https://review.opendev.org/#/c/747796/
>
> >
> > [3]
> https://opendev.org/opendev/system-config/src/branch/master/playbooks/roles/gitea/templates/app.ini.j2#L88-L95
> > [4]
> https://opendev.org/opendev/system-config/src/branch/master/docker/gitea/Dockerfile#L92-L94
> >
> >> --
> >> Jeremy Stanley
> >
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-discuss/attachments/20200830/74cc351b/attachment.html>