Excerpts from sfinucan's message of 2017-07-10 17:20:37 +0100: > On Fri, 2017-07-07 at 15:58 +0100, sfinu...@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 > __________________________________________________________________________ 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