Open Stack

On Mon, Jul 10, 2017 at 12:20 PM,  <sfinucan at redhat.com> wrote:
> 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.

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-request at 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