[all] READMEs of zuul roles not rendered properly - missing content
Hello everyone, 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 Thanks, -- Martin Kopec Quality Engineer Red Hat EMEA <https://www.redhat.com> <https://red.ht/sig>
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
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/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.
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/... [4] https://opendev.org/opendev/system-config/src/branch/master/docker/gitea/Doc...
-- Jeremy Stanley
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/... [4] https://opendev.org/opendev/system-config/src/branch/master/docker/gitea/Doc...
-- Jeremy Stanley
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@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/...
[4] https://opendev.org/opendev/system-config/src/branch/master/docker/gitea/Doc...
-- Jeremy Stanley
participants (4)
-
Brian Rosmaita
-
Clark Boylan
-
Jeremy Stanley
-
Martin Kopec