Open Stack

Excerpts from Sean Dague's message of 2017-08-08 17:01:29 -0400:
> When trying to import
> https://github.com/openstack/openstack-manuals/blob/6f9fc171800e8a435011f38cd4558e900884ce86/doc/config-reference/source/compute/hypervisor-vmware.rst#L2
> into the Nova admin config reference
> (https://review.openstack.org/#/c/491853), a couple of interesting
> challenges popped up. These pop up in a couple of other places, but this
> one file nicely contains both of them.
> 
> The first is the common autogenerated files (like
> https://github.com/openstack/openstack-manuals/blob/6f9fc171800e8a435011f38cd4558e900884ce86/doc/config-reference/source/tables/nova-vmware.rst#L11).
> To the best of my knowledge we don't have that autogeneration tooling in
> the projects. Should we just be copy/pasting this content in? Is there
> another better strategy there?

oslo.config does have an extension for generating a table-format
list of all of the configuration options, and the idea is to replace
those included tables with the 'show-options' directive. It uses
the same inputs as the sample file generator. See
https://docs.openstack.org/oslo.config/latest/reference/sphinxext.html for
details

The "filtering" ability is limited right now to namespaces. You may not
be able to reproduce exactly the tables that were used in earlier
releases. We've asked for feedback about other capabilities that teams
want for building tables containing subsets of the input options, and if
we find contributors to build those features we can add them for Queens.

In the mean time, if the output doesn't meet your needs, you can
copy in the tables from the old guide. They aren't up to date, so
you may want to look at the tool for generating the tables in the
openstack-doc-tools repo.

> The second is cross references that don't yet exist. In this case -
> https://github.com/openstack/openstack-manuals/blob/6f9fc171800e8a435011f38cd4558e900884ce86/doc/config-reference/source/compute/hypervisor-vmware.rst#L981.
> Which is :ref:`block_storage_vmdk_driver`, that would be in the cinder
> manual, but does not seem to yet be there. I'm not sure what the best
> strategy is here. Just a TODO to find the right cinder ref once it shows up?

jungleboyj is working on the cinder docs, so he may have some idea of
when those are expected to land. In the mean time, a TODO with a link to
some page in the cinder docs seems like a good temporary measure.

> 
> If anyone has thoughts on the best resolutions here, that would be great.
> 
>     -Sean
>