[openstack-dev] [all][docs] Incorrect '/p' in Project Source URLs on docs.openstack.org/developer
fungi at yuggoth.org
Fri Oct 16 15:46:33 UTC 2015
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:
Problem here is, _html_page_context() assumes currently that the
origin in your repo will always be in the form of:
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.
More information about the OpenStack-dev