On 08/12/2016 01:43 PM, Jim Rollenhagen wrote:
> On Thu, Aug 11, 2016 at 6:13 PM, John Dickinson <m...@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
__________________________________________________________________________
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
