Open Stack

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.

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.

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