Open Stack

On Mon, Jul 10, 2017 at 1:11 PM, Doug Hellmann <doug at doughellmann.com> wrote:
> 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?

The theme shows "current" - however I noticed while reviewing this
morning the nomenclature is "latest" in the URL, so I will make a
change. Do you suggest "latest -n.n.n" as the string value, or simply
"latest"?

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.
>
> 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-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