Open Stack

On 08/08/2016 08:44 AM, Doug Hellmann wrote:
> Excerpts from Hayes, Graham's message of 2016-08-08 11:28:35 +0000:
>> On 05/08/2016 19:15, Doug Hellmann wrote:
>>> Excerpts from Hayes, Graham's message of 2016-08-05 17:04:35 +0000:
>>>> Hey,
>>>>
>>>> We look like we are getting close to merging the os-api-ref integration
>>>> with openstackdocstheme.
>>>>
>>>> Unfortunately, there is no "phased" approach available - the version
>>>> released with compatibility for openstackdocstheme will not work
>>>> with oslo.sphinx.
>>>
>>> In what way doesn't it work? Is one of the themes missing something?
>>>
>>> Doug
>>
>> Both themes are laid out differently. One uses bootstrap and the other
>> doesn't, one has a different view on what should be hidden, and where
>> TOCs belong.
>>
>> The end result was that for the oslosphinx integration we included extra
>> CSS / JS, but that code can cause conflicts with openstackdocstheme.
> 
> Would putting that extra stuff into oslosphinx, as an optional part of
> the them, make the transition any easier?

It's actually somewhat the inverse problem (IIRC).

oslosphinx is written as an appropriate sphinx extension / theme, it
plays nice with others. You can tell the author(s) were familiar with
sphinx.

openstackdocstheme was done as a bootstrap UX, then grafted into sphinx
builds in a way that just barely works, as long as you don't include any
other sphinx extensions. The moment you do, things get really funky.
Given that it does things like carry it's own jquery (needed by
bootstrap), instead of doing the standard scripts include in sphinx.
This was clearly written by folks that were familiar with boostrap, and
not really with sphinx.

When we hacked together os-api-ref the incompatibilities with
openstackdocstheme were getting in the way, so it was done with
oslosphinx in mind. There were definitely styling elements we needed
differently, and instead of negotiating changing the style on everything
else, that styling was done in os-api-ref.

os-api-ref also needs some dynamic elements. For instance, section
expand / collapse, and sensible bookmarking. In a perfect world that
probably ends up in the theme layer, which means doing it in both
oslosphinx and openstackdocstheme, the extension only creating base markup.

However, the goal isn't to support both. It's to support
openstackdocstheme which is the strategic UX for all openstack docs
(even though it's actually not very sphinxy, which is a whole other
issue that will probably hurt us other places).

So, we could do a lot of work to smooth the transition, which would get
thrown away shortly after, or just create a flag day and have docs
broken for a bit until people get across it.

	-Sean

-- 
Sean Dague
http://dague.net