Build .rst files for viewing in cgit

[Elizabeth K. Joseph]

Github has the nice feature of converting the .rst files for viewing in the browser through the web interface. Look into doing this in cgit as well and confirm this the desired behavior by users.

[Jeremy Stanley (fungi)]

I'm torn on this, because while I do like the autorendering of .rst files, I also like to be able to view them as source code too (something GitHub doesn't let you do either, at least aside from "raw" mode where there are no linkable line numbers/syntax highlighting either). But I also don't spend a lot of time in a browser, so I'm not particulary opposed if there's sufficient interest in it from others.

[Elizabeth K. Joseph (lyz)]

Included in cgit these days is automatic parsing of files in order to display them on an /about page for the repository, which is linked in the top header (see screenshot), this is done simply by adding a few lines in the cgitrc file.

Attached is how it looks with this enabled for nova's README.rst

Compare to github (scroll down to the bottom): https://github.com/openstack/nova

And just the raw output of browsing to README.rst manually in the tree (which is arguably less discoverable than a linked /about in the menu): https://git.openstack.org/cgit/openstack/nova/tree/README.rst

This uses the default /usr/libexec/cgit/filters/about-formatting.sh that ships with cgit that uses rst2html (or md2html) for converting text, if we want it to be "prettier" we can work with changing what is used for the conversions and serving up a custom about-formatting.sh.

Applying rst2html filters to all .rst files is a bit more of a complicated effort.

[Jeremy Stanley (fungi)]

This seems like a fine compromise to me.

[Elizabeth K. Joseph (lyz)]

Actually, that's what it looks like when you get into a fight with SELinux and everything defaults to text2html. Attached how it looks when SELinux is tamed and rst2html can be used, much better! Review coming soon.

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/60375

[Elizabeth K. Joseph (lyz)]

The current issue here is that the cgit mechanism for rendering .rst (and other) README files is that it allows Apache to run straight bash conversion commands on the files and serves them without any type of sanitation.

All the README files are reviewed, so it may not be a serious issue, but it does seem a little scary that we have our webserver doing this - and SELinux agrees.

[OpenStack Infra (hudson-openstack)]

Change abandoned by Elizabeth K. Joseph (<email address hidden>) on branch: master
Review: https://review.openstack.org/60375
Reason: Since cgit's built-in mechanism for doing this isn't very safe (executing bash scripts upon page load and directly displaying results), I'm going to abandon this for now.

We may want to work upstream cgit to develop a safer mechanism that at least uses input sanitation.