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