Open Stack

Andreas,

I would advocate for NOT moving flagmappings files to individual project
repositories.   Having worked out recently how configuration tables are
generated and was able to generate them myself I considered how to improve
the process in relation to using the existing oslo.config generation tools.

The primary reason for not moving the flagmappings file is you are then
dependent on the projects review cycle (and processes) to get these changes
approved.  This includes the load on the gate, and applicable +2 by cores
(which on major projects have their own priorities for features) etc.  I
would not like to see documentation generation data dependent on all
applicable projects.

I see the bigger issue is the current process for generating the config
guides including the frequency and accuracy during the cycle.

In a nutshell, it's a huge pull process, where at some time somebody runs
the tools which pulls in all projects, and dependencies and uses a doc
specific version to identify all the config options, merge with
flagmappings and produce configuration tables.

Ideally, a more optimal means is to create a push process, that is, if any
configuration settings changes within a project during a commit, this data
change is pushed, so that the documentation can be updated accordingly when
applicable.  Nice in theory, in practice it's more complex. Some high level
thoughts on the process.

Some projects now can generate a sample configuration file (tox
-egenconfig).  In Oslo we are hoping to increase this usage, and use the
developer docs as a place to store these files within a project repo.
Leveraging this existing functionality, if we could detect a change in the
sample configuration file during a review commit, then we have the
notification process (keystone already has a bot that does this) that is
the basic information trigger of a new change needed in docs for config.
Now, what is that change of configuration is more complex, and it would
seem a logical necessity to use a neutral format (e.g. yaml) to record the
parsed configuration options, and enable this format to be saved
somewhere/somehow.  This becomes both the input to the oslo.config
generator (i.e. we effectively take current functionality and split it into
two parts, the parsing of configuration options into yaml format, and the
generation of sample config files, and developer docs sphinx extensions
using the yaml format. The yaml data also forms the basis of data for the
configuration guide.
One may argue why break up the oslo.config work because it's working, well
because the inputs are used to generate multiple forms of documentation and
at present only some forms are being used.

I am certainly not familiar with the infra work for bots, and how within a
gate to create, propose and commit work of a produced yaml file, or change
in yaml file.

It does seem like this could be a lot of work, but it's the foundation of
converging the work the documentation team does with tools that exist for
the development side, as well as reducing the tool complexity that exists
in doc tools now.


Regards

Ronald




Ronald Bradford

Web Site: http://ronaldbradford.com
LinkedIn:  http://www.linkedin.com/in/ronaldbradford
Twitter:    @RonaldBradford <http://twitter.com/ronaldbradford>
Skype:     RonaldBradford
GTalk:     Ronald.Bradford
IRC:         rbradfor


On Tue, May 10, 2016 at 9:34 AM, sohan sangwan <sohaninfo at gmail.com> wrote:

> Hi Andreas,
>
> Thank you for your response.
>
> I have around 10 years work experience. I have got work experience in
> database internals, enterprise search engine, and data visulizations. I
> have earlier worked on Open Source Projects like PostgreSQL and MySQL.
>
> I am currently working on OpenStack technology in my company . I do have
> interest in Identity and access management (IAM). I am very much interested
> to support Single Sign-On for multiple(OpenStack) clouds in Horizon.
>
> I am also interested to improve OpenStack documentations. While
> configuring Keystone for Federations I faced many issues. After successful
> configurations I realized that the documentation of OpenStack has a scope
> for improvement.
>
>
> Thanks and regards,
> Sohan
>
> On Tue, May 10, 2016 at 4:44 PM, Andreas Jaeger <aj at suse.com> wrote:
>
>> On 2016-05-10 11:10, sohan sangwan wrote:
>> > Hi Andreas,
>> >
>> > Thank you for your email.
>> >
>> > I do not know current Config Reference creation works.
>> >
>> > I am sorry I do not understand all the requirements. I would be happy if
>> > I could be assigned some small task.
>> > I woul be glad to do that so that I could also learn.
>> >
>> > Appreicate your help!
>> >
>>
>> Sohan, plesae tell us a bit more about you and how you want to help and
>> I hope that then somebody can propose a few projects.
>>
>> Also, read the current specs and discussion on the mailing list - and
>> speak up where you want to help,
>>
>> Andreas
>> --
>>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
>>   SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>>    GF: Felix Imendörffer, Jane Smithard, Graham Norton,
>>        HRB 21284 (AG Nürnberg)
>>     GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
>>
>>
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20160510/4e91476f/attachment-0001.html>