Open Stack

On 08/12/2016 01:43 PM, Jim Rollenhagen wrote:
> On Thu, Aug 11, 2016 at 6:13 PM, John Dickinson <me at not.mn> wrote:
>>
>>
>> On 11 Aug 2016, at 15:02, Brian Rosmaita wrote:
>>
>>> I have a question about the api-ref. Right now, for example, the new
>>> images v1/v2 api-refs are accurate for Mitaka.  But DocImpact bugs are
>>> being generated as we speak for changes in master that won't be
>>> available to consumers until Newton is released (unless they build from
>>> source). If those bug fixes get merged, then the api-ref will no longer
>>> be accurate for Mitaka API consumers (since it's published upon update).
>>>
>>> My question is, how should we handle this? We want the api-ref to be
>>> accurate for users, but we also want to move quickly on updates (so that
>>> the updates actually get made in a timely fashion).
>>>
>>> My suggestion is that we should always have an api-ref available that
>>> reflects the stable releases, that is, one for each stable branch.  So
>>> right now, for instance, the default api-ref page would display the
>>> api-ref for Mitaka, with links to "older" (Liberty) and "development"
>>> (master).  But excellent as that suggestion is, it doesn't help right
>>> now, because the most accurate Mitaka api-ref for Glance, for instance,
>>> is in Glance master as part of the WADL to RST migration project.  What
>>> I'd like to do is publish a frozen version of that somewhere as we make
>>> the Newton updates along with the Newton code changes.
>>>
>>> Thus I guess I have two questions:
>>>
>>> (1) How should we version (and publish multiple versions of) the api-ref
>>> in general?
>>>
>>> (2) How do we do it right now?
>>>
>>> thanks,
>>> brian
>>>
>>
>> I was working with the oslosphinx project to try and solve this issue in a cross-project way for the dev docs. I think the ideas there could be useful here.
>>
>> Basically, if you have docs built every commit (instead of every release, like normally happens with library projects), you can set show_other_versions to True and get a sidebar link of versions based on tags. (Yeah, I know it wasn't working earlier, but that should be fixed now).
>>
>> So with this process, keep building docs per commit so you have the latest available. But turn on the sidebar links for other versions, and you can have a place for docs from the last few releases in your project. I'm not sure that it would work well for stable branches that are updated (but really, if you're updating stable, how "stable" is it?)
> 
> We actually publish per-release dev docs right now, though the sidebar
> seems broken:
> 
> master: http://docs.openstack.org/developer/swift/
> stable release: http://docs.openstack.org/developer/swift/mitaka/
> intermediate release: http://docs.openstack.org/developer/swift/2.9.0/


The latest oslosphinx theme should fix these.

Note also that you need to set a variable in conf.py to turn on the
sidebar - it was turned on by default for some time (and there was no
variable to turn it off) and now there's there's a variable and default
is off,

Andreas
-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
       HRB 21284 (AG Nürnberg)
    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126