[openstack-dev] [all][docs] Incorrect '/p' in Project Source URLs on docs.openstack.org/developer
Doug Hellmann
doug at doughellmann.com
Fri Oct 16 16:59:29 UTC 2015
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.
>
More information about the OpenStack-dev
mailing list