On 4/5/19 10:06 PM, Thomas Goirand wrote:
Hi,
In may docs, I can see stuff like this, especially in README.rst:
.. image:: http://governance.openstack.org/badges/something.svg :target: http://governance.openstack.org/reference/tags/index.html
I'd like to let everyone know that, from a package maintainer perspective, and considering that we do package your Sphinx doc in distros, this is an annoyance. Indeed, I do feel like I must patch it out and remove the external source.
The reason is, as a Debian user, I do not expect my browser to do external queries to a website when I'm browsing a local documentation. This one is on openstack.org, it's mildly ok-ish, though, I'm removing the image still. There's other more annoying stuff (think: travis, github, and other spies which we don't control).
FWIW - it would be exceptually strange for OpenStack projects to include travis or github badges in documentation since we don't use those services. Which is to say - for things that aren't governance badges, I'd be curious to learn about and erradicate such things.
So, it'd be nice if these images with external resources were completely avoided in OpenStack docs. Either by simply not putting such useless image, replacing it by text only, or by embedding the image itself in the doc (or in openstackdocstheme? I suspect that's not what people want, they want it to be displayed in github... so embedding would be the only solution).
opendev.org will now show these too - so I believe they are 'desirable' in README files. Perhaps instead of trying to get rid of them or make things extra harder for folks - we could consider ending the practice of doing a sphinx include of the README.rst content in the docs. Perhaps we can find a good pattern for having a README with badge types of things that includes actual content from the docs? I'm not sure how well include paths work in the opendev RST renderer - but might be worth exploring. Then we could have clean docs and badged READMEs. Or?