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

Thomas Goirand zigo at debian.org
Mon Dec 7 16:28:13 UTC 2015


On 12/07/2015 03:04 PM, Morgan Fainberg wrote:
> 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.

Yes please.

> 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.

Yup.

> 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.

Thanks for this very accurate recap.

>> * We should ensure we are only loading any external sources via HTTPS
>> rather than HTTP.
>
> Or better yet, not loading any external sources at all (though
> figuring out how to find and link to locally installed distro
> packages of fonts and similar resources might get complicated, and
> so may still be easier left as distro-specific patches in their
> respective packaging).

Most of the time, this is handled by removing the 3rdparty static
content (the font in this case), and replacing it by a symlink to the
distro's system file. Though currently, the theme doesn't include a
local copy of the font, and has no mechanism to use one. I'm not sure if
there's a way to check if a local content is present in Javascript. Any
suggestion?

By the way, why do we absolutely need a specific font? Can't we just use
what's in the system already? As far I as I remember, the awesome font
is very close from the system ones (like DejaVu, for example). Maybe
there could be such a fallback at least?

Cheers,

Thomas Goirand (zigo)




More information about the OpenStack-dev mailing list