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/1e92a67db6f5fa3f3284d5b1928f10... > 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. 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. -- Jeremy Stanley