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)