Open Stack

On 15/07/2016 22:58, Anne Gentle wrote:
> Hi -dev and -doc lists, and awesome devs Karen and Graham specifically -
>
> I want to figure out the best way to coordinate a release of both the
> theme and the sphinx extension so that we can test and publish and
> iterate on the new API reference information display and navigation.
>
> I think these patches are relevant and need to be merged:
>
> openstackdocstheme
> https://review.openstack.org/326668 (Actually include custom JS files)

This one is very important.

This would need to be merged, and then a release created so we could
use it

> https://review.openstack.org/329508 (API References dropdown menu)

I have not fully testes this one yet - I will do that this week

> os-api-ref
> https://review.openstack.org/324805 (Tests for invalid parameter files)
> https://review.openstack.org/327309 (microversion selector - dropdown)

There seems to be some rendering problems on Chrome for this one - I 
need to investigate it.

> https://review.openstack.org/318281 (HTTP Response Code Table)

Good to go, afaik.

> https://review.openstack.org/#/c/322430/ (openstackdocstheme integration)

When this merges, and is part of an os-api-ref release, all the api-ref
jobs will break. We need to find a way of putting a section in the
conf.py of each api-ref code base to flip to openstackdocstheme when it
is at the right version.

>
> I think these patches are irrelevant or will keep us from the priority
> task at hand, and it would be best not to merge them until we have
> merged and then test these after getting the above patches released:
> openstackdocstheme
> https://review.openstack.org/269297 (Remove duplicate search field
> from left sidebar)
> https://review.openstack.org/339747 (Removed more reliance on CDNs)
> https://review.openstack.org/333573 (Removed minimized files)
> https://review.openstack.org/339314 (Fix the incorrect CSS values,
> does something to headings I want more testing on)
>
> I'm asking about timing and next steps. Are these the basic steps, and
> am I missing any?

https://review.openstack.org/#/c/322453/ (Change Layout of Path + Sub
Title) needs to merge before https://review.openstack.org/#/c/322430/

This is to allow for longer URLs that Nova and Keystone have.


> 1. Review and merge the relevant patches in both os-api-ref and
> openstackdocstheme.
> 2. Release new versions of  os-api-ref and openstackdocstheme.
> 3. Publish test content with the new versions.
> 4. Update relevant tox.ini and requirements.txt files.
> 5. Rebuild all api-ref source to implement the new navigation.
>
> What I need to know:
> Is there an order we should follow in merging so that testing across
> browsers makes sense?
>
> What is the scope of testing: is testing with the Compute content
> enough or should we also test with Identity and other projects?

I *think* the URLs in identity are longer, we should use that as well.

> What timing should we attempt for steps 1 and 2 above? I'd like to aim
> for August for 1 and 2, is that do-able?

It should be, if we can get quick reviewer feedback on the patches.
For the changes to the projects conf.py, we might need to ping PTLs /
doc liaisons to make sure it gets the required attention.

> Do we need to wait for all the migrated content to be ready for steps
> 4 and 5 above? I think the answer is no, but I might be missing
> relevant info about how the navigation will work. I can also set up a
> meeting for next week if that's easier than email, let me know.
>
> Thanks,
> Anne
>