Open Stack

On 05/09/2016 09:53 AM, Lana Brindley wrote:
>>>> - Push Debconf support in separate foo-debconf-install.rst files, and
>>>> use them to generate the install-guide instead of the normal files.
>>>
>>> I don't understand what you want to do here - and especially how you do
>>> this to make it in a way that is easy to support.
>>
>> Lets take an actual example. For setting-up glance, we have
>> glance-install.rst. My proposal is to create a
>> glance-debconf-install.rst which will be used only in the case of Debian
>> when using Debconf. This file will be less than 30 lines in this case
>> (as mostly, "apt-get install glance" is the only thing there is to
>> document). It will be used instead of glance-install.rst, which would go
>> out of that guide.
> 
> It sounds like you want to publish a second Debian Install Guide from the
> same Install Guide source?

Yes, because the idea is to benefits from everything else that is not
the "apt-get install foo" part. IE: configuring everything. That's the
hard part, which our users want to learn.

> If that's correct, it's not the direction we would like to go in. I'm
> all for you publishing a Debian guide that uses debconf, but it would
> need to be a separate book. We will also hopefully be publishing other
> automated ways of installing as well, so it will be in good company.

I don't want to write a book from scratch. I want to reuse the other
parts of the install-guide which don't need any special attention from
my side of things.

Let's take an actual example with Keystone. In the install guide,
there's currently these parts:

1* Identity service overview
2* Install and configure
3* Create the service entity and API endpoints
4* Create a domain, projects, users, and roles
5* Verify operation
6* Create OpenStack client environment scripts

In the Debconf guide, I'd like to rewrite 2* and 3* as this is done a
little bit different. It'd be really silly to fork all the other parts,
which are relevant to a guide using the interactive mode for Debconf.

Same way for Glance, where 2 parts would stay untouched, and only the
install would change.

So, by all means, let's publish it somewhere else if you wish. But I
really would like to reuse some of the source.

>> Also, I doubt that we need a spec for implementing this. We're also all
>> short in time, I can already foresee the spec taking months to be
>> approved, with comments on the English wording of the spec and so on...
>> Please let's avoid this and simply discuss it in this list!
> 
> We're usually not too slow approving specs, especially at this point in the cycle. Please create one.

Let's discuss here first, if you don't mind. It seems there's still some
misunderstanding that needs to be cleared.

On 05/09/2016 06:58 PM, Anne Gentle wrote:
> I don't think "delete, spec, re-add" is what is proposed above. I
> think it's "revise, test, re-add links," where revise means to match
> the rest of the source files, without debconf.

Instead of weakly describing what I would like to do, I wrote a patch:
https://review.openstack.org/#/c/314020/

It currently fails, I'm not sure why, but the point was to show my
intentions, and discuss it here first. If we're on the same page, then
I'll go ahead and attempt to fix the issues. Could you have a look?

[Maybe don't discuss here the technical problems of the patch, that can
be done in the patch itself, as a review: it'd be more helpful there]

On 05/09/2016 06:58 PM, Anne Gentle wrote:
> Conditionals in index.rst and toctrees are super buggy.
> See
http://lists.openstack.org/pipermail/openstack-docs/2015-February/005863.html
This
> is a good example of why a spec helps us all get clarity and avoid
> pitfalls.

I'm surprised to read that, knowing that the main index.rst already has
such conditionals.

Exactly where should I look for debugging these conditional TOCs? Do you
have an actual non-working example? I'd like to have a go at trying to
debug it for sure (though I trust you when you say it's hard to debug,
so I can't promise to fix, but I'm at least curious...).

On 05/09/2016 06:58 PM, Anne Gentle wrote:
> It has become clear on the list that we don't all understand the
> proposed plan, heh. Pretty sure your current proposal needs some
> technical review if you're thinking about using conditionals in
> toctree because it simply won't work unless you're better at
> debugging than I am (would be nice if you are). I empathize with the
> "fast, please" request, but at the same time, we don't want to
> misstep (and trip) due to speed.

I suppose that the patch I've wrote and linked above is better than a
spec where I may very badly explain. It's not that I'm not willing to do
the work of writing a spec, it's just that I don't think I'm very good
with that format, and probably we may understand each other better
either in this list, or with an example patch. If that's still not
enough, maybe we can discuss it more here in the list, then if that's
still not enough, I'll kill myself... :)

Cheers,

Thomas Goirand (zigo)