On Mon, Jul 10, 2017 at 12:20 PM, <sfinu...@redhat.com> wrote: > 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.
The 1.12.0 release of openstackdocstheme provides an option to get to more than the current version of a project's docs. It acquires the values by querying the most recent five git tags: https://review.openstack.org/#/c/477639/ Anne > > 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 > > __________________________________________________________________________ > 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 -- Read my blog: justwrite.click Subscribe to Docs|Code: docslikecode.com __________________________________________________________________________ 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
