Open Stack

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.

[1] http://codesearch.openstack.org/?q=nonlocal_uri&i=nope&files=&repos=

> On Apr 8, 2020, at 12:54 PM, Dmitry Tantsur <dtantsur at redhat.com> wrote:
> 
> 
> 
> On Wed, Apr 8, 2020 at 6:50 PM Thomas Goirand <zigo at debian.org <mailto: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/dae929a0/attachment.html>