Re: [openstack-dev] [api][os-api-ref] openstackdocstheme integration
On 08/08/2016 08:44 AM, Doug Hellmann wrote: > Excerpts from Hayes, Graham's message of 2016-08-08 11:28:35 +: >> On 05/08/2016 19:15, Doug Hellmann wrote: >>> Excerpts from Hayes, Graham's message of 2016-08-05 17:04:35 +: 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 __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api][os-api-ref] openstackdocstheme integration
On 08/08/2016 13:47, Doug Hellmann wrote: > Excerpts from Hayes, Graham's message of 2016-08-08 11:28:35 +: >> On 05/08/2016 19:15, Doug Hellmann wrote: >>> Excerpts from Hayes, Graham's message of 2016-08-05 17:04:35 +: 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? > > Doug I don't think so - with the changes to the structure of the HTML things will be broken anyway. It is unfortunate, but I think we have a better chance of doing the cut over now, before more projects start using the library. If everyone agrees with the patch for the phased roll over, I can submit the patches to all the required repos, and help them get merged. Graham >> >> As one theme already uses bootstrap, the css (and the classes applied >> to the HTML elements) has to be modified, and is incompatible with the >> old theme, as it was only using the sideloaded bootstrap css in a >> section of the page. >> >> The review for the integration is here: >> >> https://review.openstack.org/#/c/322430/ >> >> - Graham >> >>> So, we need a way to use oslosphinx until it is released, and the new theme after it is released. I suggest we put a temporary section of code in the `conf.py` of each project using os-api-ref - I have a WIP preview for designate up for review [0] Can I get some feedback, if people think this is a good way forward? The list of repos I have using os-api-ref is (from [1]: openstack/networking-sfc openstack/ceilometer openstack/glance openstack/heat openstack/ironic openstack/keystone openstack/manila openstack/designate openstack/neutron-lib openstack/nova openstack/sahara openstack/searchlight openstack/senlin openstack/swift openstack/zaqar Thanks, Graham 0 - https://review.openstack.org/#/c/351800/ 1 - http://codesearch.openstack.org/?q=os_api_ref=nope=api-ref%2Fsource%2Fconf.py= >>> >>> __ >>> OpenStack Development Mailing List (not for usage questions) >>> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe >>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev >>> >> > > __ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api][os-api-ref] openstackdocstheme integration
Excerpts from Hayes, Graham's message of 2016-08-08 11:28:35 +: > On 05/08/2016 19:15, Doug Hellmann wrote: > > Excerpts from Hayes, Graham's message of 2016-08-05 17:04:35 +: > >> 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? Doug > > As one theme already uses bootstrap, the css (and the classes applied > to the HTML elements) has to be modified, and is incompatible with the > old theme, as it was only using the sideloaded bootstrap css in a > section of the page. > > The review for the integration is here: > > https://review.openstack.org/#/c/322430/ > > - Graham > > > > >> So, we need a way to use oslosphinx until it is released, and the new > >> theme after it is released. > >> > >> > >> I suggest we put a temporary section of code in the `conf.py` of each > >> project using os-api-ref - I have a WIP preview for designate up for > >> review [0] > >> > >> Can I get some feedback, if people think this is a good way forward? > >> > >> The list of repos I have using os-api-ref is (from [1]: > >> > >> openstack/networking-sfc > >> openstack/ceilometer > >> openstack/glance > >> openstack/heat > >> openstack/ironic > >> openstack/keystone > >> openstack/manila > >> openstack/designate > >> openstack/neutron-lib > >> openstack/nova > >> openstack/sahara > >> openstack/searchlight > >> openstack/senlin > >> openstack/swift > >> openstack/zaqar > >> > >> Thanks, > >> > >> Graham > >> > >> 0 - https://review.openstack.org/#/c/351800/ > >> 1 - > >> http://codesearch.openstack.org/?q=os_api_ref=nope=api-ref%2Fsource%2Fconf.py= > >> > > > > __ > > OpenStack Development Mailing List (not for usage questions) > > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > > __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api][os-api-ref] openstackdocstheme integration
On 05/08/2016 19:15, Doug Hellmann wrote: > Excerpts from Hayes, Graham's message of 2016-08-05 17:04:35 +: >> 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. As one theme already uses bootstrap, the css (and the classes applied to the HTML elements) has to be modified, and is incompatible with the old theme, as it was only using the sideloaded bootstrap css in a section of the page. The review for the integration is here: https://review.openstack.org/#/c/322430/ - Graham > >> So, we need a way to use oslosphinx until it is released, and the new >> theme after it is released. >> >> >> I suggest we put a temporary section of code in the `conf.py` of each >> project using os-api-ref - I have a WIP preview for designate up for >> review [0] >> >> Can I get some feedback, if people think this is a good way forward? >> >> The list of repos I have using os-api-ref is (from [1]: >> >> openstack/networking-sfc >> openstack/ceilometer >> openstack/glance >> openstack/heat >> openstack/ironic >> openstack/keystone >> openstack/manila >> openstack/designate >> openstack/neutron-lib >> openstack/nova >> openstack/sahara >> openstack/searchlight >> openstack/senlin >> openstack/swift >> openstack/zaqar >> >> Thanks, >> >> Graham >> >> 0 - https://review.openstack.org/#/c/351800/ >> 1 - >> http://codesearch.openstack.org/?q=os_api_ref=nope=api-ref%2Fsource%2Fconf.py= >> > > __ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api][os-api-ref] openstackdocstheme integration
Excerpts from Hayes, Graham's message of 2016-08-05 17:04:35 +: > 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 > So, we need a way to use oslosphinx until it is released, and the new > theme after it is released. > > > I suggest we put a temporary section of code in the `conf.py` of each > project using os-api-ref - I have a WIP preview for designate up for > review [0] > > Can I get some feedback, if people think this is a good way forward? > > The list of repos I have using os-api-ref is (from [1]: > > openstack/networking-sfc > openstack/ceilometer > openstack/glance > openstack/heat > openstack/ironic > openstack/keystone > openstack/manila > openstack/designate > openstack/neutron-lib > openstack/nova > openstack/sahara > openstack/searchlight > openstack/senlin > openstack/swift > openstack/zaqar > > Thanks, > > Graham > > 0 - https://review.openstack.org/#/c/351800/ > 1 - > http://codesearch.openstack.org/?q=os_api_ref=nope=api-ref%2Fsource%2Fconf.py= > __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[openstack-dev] [api][os-api-ref] openstackdocstheme integration
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. So, we need a way to use oslosphinx until it is released, and the new theme after it is released. I suggest we put a temporary section of code in the `conf.py` of each project using os-api-ref - I have a WIP preview for designate up for review [0] Can I get some feedback, if people think this is a good way forward? The list of repos I have using os-api-ref is (from [1]: openstack/networking-sfc openstack/ceilometer openstack/glance openstack/heat openstack/ironic openstack/keystone openstack/manila openstack/designate openstack/neutron-lib openstack/nova openstack/sahara openstack/searchlight openstack/senlin openstack/swift openstack/zaqar Thanks, Graham 0 - https://review.openstack.org/#/c/351800/ 1 - http://codesearch.openstack.org/?q=os_api_ref=nope=api-ref%2Fsource%2Fconf.py= __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
