Open Stack

Excerpts from Jeremy Stanley's message of 2015-10-16 15:46:33 +0000:
> On 2015-10-16 15:03:57 +0000 (+0000), Neil Jerram wrote:
> [...]
> > Surely it must be intended to be browseable?  If it was intended as a
> > clone URL, shouldn't it be presented in plain text, instead of as a link?
> 
> That's my assumption as well. So given this, it's probably better to
> think about our cgit interface URLs as being:
> 
>     http(s)://git.openstack.org/cgit/<namespace>/<project>
> 
> Problem here is, _html_page_context() assumes currently that the
> origin in your repo will always be in the form of:
> 
>     <protocol>://<hostname>/<namespace>/<project>
> 
> This is a bad assumption for a couple reasons:
> 
>   * Depending on how the job is constructed in our CI, the origin
>     may be reset to a proxied URL which isn't formed in the expected
>     fashion. In this case you can see it happen in a recent job
>     log[*], demonstrating this as the underlying source of the
>     unexpected URL path.

OK, I didn't realize we did this.

> 
>   * You never know what the form of a developer's local origin URL
>     might be, so this is likely locally broken for a lot of people
>     anyway. For example, I usually clone with a .git extension on
>     the URL because I'm a pedant (there are plenty of ways this
>     assumption could go wrong, this is merely one of them).

I wasn't worried about supporting the local build case for this. Do you
think we need to?

> 
> There are probably a few ways to go about tweaking oslosphinx to
> correct this. In my mind, for the sake of reusability, it would make
> most sense to do something like:
> 
> 1.  Check some documented envvar like OPENSTACK_PROJECT_NAME and
>     expect it to contain something in the form of
>     <namespace>/<project>. This way we can explicitly set it in our
>     CI jobs to an already populated variable like ZUUL_PROJECT which
>     contains this information.

That sounds like way more work than is useful for such a small
feature.

> 
> 2.  If OPENSTACK_PROJECT_NAME is not set, check an optional
>     extension parameter in doc/source/conf.py so that projects can
>     explicitly set their source URL (this improves downstream
>     consumability of the extension).

Defining a config value and updating every project to set it also seemed
like more work than the outcome warranted. Defining the option is easy,
but that's a lot of project patches.

> 
> 3.  If there's no envvar or Sphinx config override, guess from the
>     origin with a somewhat more thorough regex like
>     '/([^/]+/[^/]$)(\.git|)$' to be able to omit leading path nodes
>     and any .git extension. This is also not perfect, but is at
>     least better than the present situation and will get these links
>     working correctly on docs.openstack.org for now.
>