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