Open Stack

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.

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

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.

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

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.

-- 
Jeremy Stanley