[all][infra] READMEs of zuul roles not rendered properly - missing content
fungi at yuggoth.org
Mon Aug 24 14:36:18 UTC 2020
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.  .
> 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?
>  https://opendev.org/openstack/tempest/src/branch/master/roles/run-tempest
>  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
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.
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.
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 963 bytes
Desc: not available
More information about the openstack-discuss