Template Guide: required status of nested properties not documented

[Zane Bitter]

In the Resource reference of the Template Guide:

https://docs.openstack.org/heat/latest/template_guide/openstack.html

we group top-level properties of resources into Required and Optional sections. However, where properties are themselves Maps that have subproperties, we don't separate the subproperties into Required and Optional so the user has no way of telling without looking at the code.

e.g. under
https://docs.openstack.org/heat/latest/template_guide/openstack.html#OS::Neutron::Port-prop-allowed_address_pairs the subproperty "ip_address" is required whereas "mac_address" is not,[1] but you'd never know that from the docs.

[1] http://git.openstack.org/cgit/openstack/heat/tree/heat/engine/resources/openstack/neutron/port.py?h=stable%2Focata#n232

[Kaz Shinohara (kazsh)]

Let me work for this, suppose we can make it by upgrading /doc/source/ext/resource.py

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/490805

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/490805
Committed: https://git.openstack.org/cgit/openstack/heat/commit/?id=50088c572e5abe3001db47e35875a3dfe47e8381
Submitter: Zuul
Branch: master

commit 50088c572e5abe3001db47e35875a3dfe47e8381
Author: kaz_shinohara <email address hidden>
Date: Fri Aug 4 17:22:43 2017 +0900

    Updated the template guide.

    The current template guide does not show required/optional flag
    for subproperties, it means that users need to look at the source
    code to clarify if the subproperties is required or not.
    Updated a sphinx extension doc/ext/resource.py to display
    required/optional flag for subproperties.

    Change-Id: Ie9e23d633d749aa7ad087330520cd3b83294794a
    Closes-Bug: #1694748

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/heat 10.0.0.0b3 development milestone.