[all] Removing privacy breaches in doc
mordred at inaugust.com
Sat Apr 6 16:16:58 UTC 2019
On 4/5/19 10:06 PM, Thomas Goirand wrote:
> 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.
More information about the openstack-discuss