[openstack-dev] [all][docs] Incorrect '/p' in Project Source URLs on docs.openstack.org/developer

Jeremy Stanley fungi at yuggoth.org
Fri Oct 16 17:49:00 UTC 2015

On 2015-10-16 12:59:29 -0400 (-0400), Doug Hellmann wrote:
> Excerpts from Jeremy Stanley's message of 2015-10-16 15:46:33 +0000:
> >   * 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?

I suppose not, unless people testing their documentation changes
locally expect to see that link work. I agree it seems like a bit of
a corner case.

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

I mainly bring it up because the project name is known to the build
environment, if only oslosphinx had some means to be told the actual
value rather than having to separately guess it based on less
accurate mechanisms.

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

However, it does make it possible for projects to use this feature
in oslosphinx even if they're not using our hosting infrastructure.
Again, probably a corner case so not a necessary usage for us to
support I guess.
Jeremy Stanley

More information about the OpenStack-dev mailing list