
<html><head><meta http-equiv="Content-Type" content="text/html; charset=us-ascii"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; line-break: after-white-space;" class="">Sphinx supports exiting with an error for any external references like images. Only a few projects are suppressing that warning [1], but perhaps not every project is treating sphinx warnings as errors that break the build.<div class=""><br class=""></div><div class="">[1] <a href="http://codesearch.openstack.org/?q=nonlocal_uri&i=nope&files=&repos=" class="">http://codesearch.openstack.org/?q=nonlocal_uri&i=nope&files=&repos=</a><br class=""><div><br class=""><blockquote type="cite" class=""><div class="">On Apr 8, 2020, at 12:54 PM, Dmitry Tantsur <<a href="mailto:dtantsur@redhat.com" class="">dtantsur@redhat.com</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><br class="Apple-interchange-newline"><br style="caret-color: rgb(0, 0, 0); font-family: Helvetica; font-size: 14px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration: none;" class=""><div class="gmail_quote" style="caret-color: rgb(0, 0, 0); font-family: Helvetica; font-size: 14px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; word-spacing: 0px; -webkit-text-stroke-width: 0px; text-decoration: none;"><div dir="ltr" class="gmail_attr">On Wed, Apr 8, 2020 at 6:50 PM Thomas Goirand <<a href="mailto:zigo@debian.org" class="">zigo@debian.org</a>> wrote:<br class=""></div><blockquote class="gmail_quote" style="margin: 0px 0px 0px 0.8ex; border-left-width: 1px; border-left-style: solid; border-left-color: rgb(204, 204, 204); padding-left: 1ex;">Hi Guys!<br class=""><br class="">Thanks for participating in this thread. I feel less alone now! :)<br class=""><br class="">On 4/6/20 11:18 PM, Jeremy Stanley wrote:<br class="">> Maybe we<br class="">> could make it easier to have our documentation builds strip that<br class="">> content automatically so that distro package maintainers don't need<br class="">> to?<br class=""><br class="">That'd be really awesome!<br class=""><br class="">On 4/7/20 3:52 PM, Jeremy Stanley wrote:<br class="">> My point was that these badges<br class="">> are mostly only relevant to folks browsing README files in a source<br class="">> code hosting platform, but when the README is embedded into a<br class="">> compiled Sphinx document they seem really out of place and are<br class="">> probably best omitted.<br class=""><br class="">Yes. Not only that. In Debian we consider this a "privacy breach" (see<br class="">below).<br class=""><br class="">On 4/7/20 5:00 PM, Sean Mooney wrote:<br class="">> for what its worth im not sure why this thread was suddenly revied<br class="">> after 6 months<br class=""><br class="">Because, as for each new release of OpenStack over the last 9 years, I'm<br class="">being moronic about re-occurring issues in the Debian packages I<br class="">maintain, and I didn't want to skip this tradition! :)<br class=""><br class="">On 4/7/20 5:58 PM, Jeremy Stanley wrote:<br class="">> Some projects put a thorough introduction in their README.rst and<br class="">> don't want to have to duplicate it all in the Sphinx doc source tree<br class="">> so just stick a ".. include:: ../../README.rst" line into<br class="">> doc/source/index.rst or a similar document. It's typical for Debian<br class="">> packages (though I haven't looked at Thomas's) to put the raw readme<br class="">> somewhere like /usr/share/doc/foo/README.rst but also stick HTML<br class="">> builds of the full documentation in a place like<br class="">> /usr/share/doc/foo/html/<br class=""><br class="">I typically only ship the HTML documentation, as I feel like it looks<br class="">much nicer than just the rst format. If one wants the raw format, well<br class="">we do have source packages... :)<br class=""><br class="">> The entire point of shipping these HTML builds in the compiled<br class="">> packages is so that users have a local copy of documentation even if<br class="">> they're somewhere with no working Internet access, and can even<br class="">> build them from local copies of the source packages without working<br class="">> Internet, therefore they need to not depend on external assets out<br class="">> on the Internet and have to instead be buildable with only what's<br class="">> packaged in the distro.<br class=""><br class="">Yes. But in this case, the problem is that the resulting HTML<br class="">documentation ends up with an image looking like this:<br class=""><br class=""><img src="http://<something-not-on-my-laptop>/ ...<br class=""><br class="">which means:<br class=""><br class="">1/ the image wont display without internet<br class="">2/ it will make a query to a website, revealing to a 3rd party that I'm<br class="">browsing the documentation. That's a privacy breach...<br class=""><br class="">Of course, the OpenStack Foundation has good intentions, and I don't<br class="">think it will make any use of these stats. Still, this is annoying.<br class=""><br class="">I therefore keep on patching these away from the README.rst, which is<br class="">exhausting, because I constantly need to rebase the patches, and it's<br class="">really all over the place on the 400+ source packages I maintain.<br class=""></blockquote><div class=""><br class=""></div><div class="">I know it's not a solution, but I wonder if it would be easier to add</div><div class=""><br class=""></div><div class=""> sed "/.. image/,+1d" README.rst</div><div class=""><br class=""></div><div class="">to your packaging instead of rebasing patches.<br class=""></div><div class=""> </div><blockquote class="gmail_quote" style="margin: 0px 0px 0px 0.8ex; border-left-width: 1px; border-left-style: solid; border-left-color: rgb(204, 204, 204); padding-left: 1ex;"><br class="">Last note: downloading the badges at build time is *not* an option (as<br class="">all distros requires to build without internet connectivity).<br class=""><br class="">Cheers,<br class=""><br class="">Thomas Goirand (zigo)</blockquote></div></div></blockquote></div><br class=""></div></body></html>