Open Stack

Excerpts from sfinucan's message of 2017-07-10 17:20:37 +0100:
> On Fri, 2017-07-07 at 15:58 +0100, sfinucan at redhat.com wrote:
> > tl;dr: pbr's 'build_spinx' derivative is broken again, and we want to just
> > remove the feature at this point. However, this is going to necessitate some
> > mechanical changes for most projects with docs and this mail serves as a
> > heads up and request for input before we proceed.
> 
> [snip]
> 
> > Here are the features that the plugin provides, along with the current
> > migration plans:
> 
> ...
> 
> > - Automatically sets project name and version using pbr's machinery
> > 
> >   Try to set this from 'openstackdocstheme'. If this isn't possible, folks 
> >   will need to add some some lines to 'conf.py' like keystoneauth does [7]
> 
> I've been looking into this particular issue further, and the more I think
> about it, the less necessary it seems. There are three configuration options
> currently set by pbr:
> 
> - project (the project name)
> - version (the full version, including alpha/beta/rc tags)
> - release (the short X.Y version)
> 
> Of these, 'project' is static and should never change, so we don't need to
> attempt to guess them. Version and release are dynamic but I've noticed we
> don't actually use them anywhere in openstackdocstheme (the version you see in
> the URL is actually an artefact of the build process and nothing to do with
> Sphinx). The closest thing we _do_ get to including version information is the
> commit ID include in header of api-ref build pages [1], which is generated by
> openstackdocstheme.

It's surprising to me that we don't include the version string anywhere
on the page. Is that an oversight in the theme, or was it on purpose?

> Given this fact, I think pbr is a providing a solution in search of problem
> here, and this feature can in fact go quietly into the night with no further
> ado.
> 
> Thoughts?
> Stephen
> 
> PS: If we really did want to include a version in the docs in the future, I
> think we could use information provided by ZUUL. I'm no ZUUL expert, but it
> seems ZUUL does have commit id info ('ZUUL_REF') and what I hope to be
> something like what 'git-describe' ('ZUUL_REFNAME'). We could simply pass these
> via the '--version' parameter to 'build_sphinx' [3]. Again though, I don't
> think this is necessary.

Relying on anything outside of the repo won't work for packagers who
build from source outside of our CI system.

> PPS: I have not responded to the other replies to this mail yet because Red
> Hat's email servers have decided not to send me replies to my own posts on
> openstack-dev. I have seen them though and will reply when I figure out how to
> get mboxes.
> 
> [1] https://developer.openstack.org/api-ref/compute/
> [2] https://github.com/openstack-infra/zuul/blob/8dda7c1/tools/trigger-job.py#L
> 54-L60
> [3] https://github.com/openstack-infra/project-config/blob/32aff86f/jenkins/scr
> ipts/run-docs.sh#L20
>