Open Stack

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.

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 963 bytes
Desc: not available
URL: <http://lists.openstack.org/pipermail/openstack-discuss/attachments/20200824/c0081478/attachment-0001.sig>