Open Stack

On Wed, Apr 8, 2020 at 6:50 PM Thomas Goirand <zigo at 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)
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-discuss/attachments/20200408/b50f9e3d/attachment-0001.html>