Open Stack

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].
> > 
> > I wonder if there were some changes in the supported README
> > syntax. Also the ".. zuul:rolevar::" syntax throws errors on
> > online rst formatters I was testing on, however, it's rendered
> > fine by md online formatters - maybe opendev.org is more rst
> > strict in case of .rst files than github?
> > 
> > Any ideas?
> > 
> > [1] https://opendev.org/openstack/tempest/src/branch/master/roles/run-tempest
> > [2] https://github.com/openstack/tempest/tree/master/roles/run-tempest
> 
> Those wrappers rely on the zuul_sphinx plugin, which needs to be
> included in docs builds thusly:
> 
> <URL: 
> https://opendev.org/zuul/zuul-jobs/src/commit/1e92a67db6f5fa3f3284d5b1928f104c428187f3/doc/source/conf.py#L24 >
> 
> That extension allows you to build job and role documentation like
> this:
> 
> https://zuul-ci.org/docs/zuul-jobs/
> 
> If the project doesn't plan to build such documentation, they can of
> course be omitted (openstack/tempest's doc/source/conf.py doesn't
> use zuul_sphinx that I can see). As far as why the README rendering
> in Gitea is tripping over it, sounds likely to be a bug in whatever
> reStructuredText parser library it uses. Was this working up until
> recently? We did just upgrade Gitea again in the past week or two.

We use pandoc to render the rst files, and the choice of tool and commands to run is driven entirely by config [3]. If we want to switch to another tool we'll want to ensure the new tool is installed in our container image [4]. Its possible that simply using the right pandoc options would get us what we want here?

> 
> 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).

[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