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