[openstack-dev] openstackdocstheme to be considered (very) harmful for your generated sphinx docs

Morgan Fainberg morgan.fainberg at gmail.com
Mon Dec 7 14:04:20 UTC 2015

On Mon, Dec 7, 2015 at 7:54 AM, Thomas Goirand <zigo at debian.org> wrote:

> On 12/04/2015 03:23 PM, Anne Gentle wrote:
> >
> >
> > On Fri, Dec 4, 2015 at 8:09 AM, Thomas Goirand <zigo at debian.org
> > <mailto:zigo at debian.org>> wrote:
> >
> >     Hi,
> >
> >     I've investigated a bit the openstackdocstheme, and tried to remove
> some
> >     of the (numerous) javascript with external references. And it's
> *very*
> >     ugly: it's full of google stuff, random CDN and so on.
> >
> >
> > I absolutely want to address these concerns.
> Hi,
> Thanks for replying.
> Let me start by this. In Debian, I'm adding this patch:
> http://anonscm.debian.org/cgit/openstack/python-openstackdocstheme.git/tree/debian/patches/patch-out-external-references.patch
> Now, let me explain why.
> > Let's start with making sure I understand the concerns so we can start
> > tracking the work requirements with bugs.
> >
> > 1. Google stuff, considered non-free. Can you list specifics? Fonts and
> > analytics js for starters, let me know if there are others?
> It's not only about non-freeness, it's also about the fact that I don't
> want Google to know when I'm browsing my local hard drive HTML, which it
> would when browsing any OpenStack docs generated by OpenStack packages
> in Debian, without the Debian patch to openstackdocstheme.
> Also, look at this from
> openstackdocstheme/theme/openstackdocs/script_footer.html (@@ -50,17
> +50,3 @@ in my patch):
> gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') +
> Well, if I'm using file:// to browse some HTML docs, then it's going to
> fetch www.google.com/cse/cse.js over a non SSL connection. That's a
> security issue.
> I believe there is the same issue with google analytics.
> > 2. Random CDN: maxcdn, which was provided to us by the Foundation's web
> > designer who gave us the design. We need CDN for performance reasons.
> > What CDN meets your requirements?
> Users browsing the local hard drive documentation don't want to access
> an external resource, even on a CDN. It would even be slower.
> The idea to speed-up browsing on the openstack.org is a very good one,
> and I salute the effort to use such a CDN. But let's not forget that the
> generated docs also end up in the distribution FOO-doc packages.
I think that this falls into the category that we need a way to add in the
CDN information for the related resources when generating the docs. The
publish job that pushes this data up to the actual websites can handle the
toggling this change. This should totally be both reasonable and accepted
(will require an infra change as well long term). I agree that the use of
the CDN for local docs is not the right choice. Clearly this is a
bug/enhancement that should be made.

> > 3. Non-minified JS, being worked on two bugs now. [1] [2]
> >
> > Does that list capture your "ugly" claim in a measureable manner?
> >
> > [1]  https://bugs.launchpad.net/openstack-manuals/+bug/1501641
> > [2]  https://bugs.launchpad.net/openstack-manuals/+bug/1502806
> >
> >     Not only this, but generated docs could potentially do call some of
> >     these objects without using HTTPS (which is the case when browsing a
> >     local *-doc package generated sphinx document using file://).
> >
> > Could you list the calls in a bug please? That will help with triaging.
> Well, last time I opened such a bug, it was closed and tagged "wontfix",
> and my patch was voted out. On patch [1], it was marked as low priority
> as well. I've seen no activity on #1502806 for a month and a half too.

> If I open such bugs again, will there be actions on them?
> >     At the present moment, I would recommend projects to *not* use the
> >     openstackdocstheme at all until all of this is fixed.
> >
> >
> > I'd like to understand your concerns further and specifically before
> > taking this type of action.
> >
> >     I'm also thinking: am I the only one in this community that cares
> about
> >     browsing privacy?
> >
> > Of course not, and with this line of reasoning and lack of clarity and
> > specificity you are not representing actual privacy concerns but trying
> > to manipulate emotions.
> See above: I'm doing this after my bug + patch were closed, so I had no
> choice but to open this kind of thread on the dev list. On the list, it
> seems taken more seriously. I'm ok to take actions myself, and propose
> patches, only if I have the insurance it wont just be denied.
There is never insurance that the patches wont be denied, but I think
you've made some reasonable arguments as to why these should be
updated/changed. I think that the non-free aspect is a bit more serious (in
my world view) than the privacy aspect for google knowing I'm looking at
docs on my local hard disk. I do also get that we all have different
priorities and they are not guaranteed to be in-sync.

> So, even after your reply, I keep saying the same thing: until these
> issues are fixed, I am giving the advice to *not* use
> openstackdocstheme, because there's security concerns.
> Also, please don't accuse me of trying to "manipulate emotions" after
> filing explicit bugs about it: the issues are real, and I have been
> explicit and specific, opening bugs in launchpad for the use of Google
> Analytics.

I think we have all agreed so far that docs should be self-contained (for
multiple reasons). Adding in Analytics could be handled in the same way as
listed above for enabling the CDN. Statically enabling google analytics is
about the same as always requiring the use of the CDN even for local
browsing. Lets keep the accusations/defence of wording choices out of the
rest of the thread and focus on getting the docs to a place that works for
all the parties. I did see the earlier comment that the external resources
(due to national firewalls) are a real impact, that alone should be enough
to encourage the changes.

So in short, I think Anne's summary is good, but is missing two items,
below I've tried to cover the things we should target to get the docs theme
in shape:

1) CDN is not useful for local browsing (and may actually be a detriment).
This can be enabled as a build-time job (as I described above)
2) Non Minified JS (actively being worked on).

The additional points are (as outlined by Thomas):

* We should not (regardless of free/non-free/etc) make sure that the docs
are fully self-contained when built locally. This would address the privacy
and security issues for the local docs. (Again Analytics can be enabled as
a build-time job).
* We should ensure we are only loading any external sources via HTTPS
rather than HTTP.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20151207/0cd487a7/attachment.html>

More information about the OpenStack-dev mailing list