Open Stack

Excerpts from Jeremy Stanley's message of 2015-10-16 17:49:00 +0000:
> 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.

Sure, it would be fine if it worked, but it doesn't seem like a
priority.

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

Maybe we can combine the ideas. Define an option with a default value
based on an environment variable, and then projects can override it if
they care about having the doc build generate that link correctly
outside of CI.

What do I need to do to expose the environment variable?

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