Open Stack

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?