Open Stack

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?)


--John




>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 801 bytes
Desc: OpenPGP digital signature
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160811/494e2561/attachment-0001.pgp>