software-config lacks docs

[Steven Hardy]

The new software-config functionality lacks sufficient documentation, in particular I noticed:

- Most of the resources don't have class level docstrings describing what they do, so we're lacking overview information in the generated template guide

- The API reference doesn't document the new API interfaces

- We (IMO) need a howto style document in addition to the template guide showing simple end-to-end examples of how the resources should be combined, along with some information on what happens wrt signalling etc (so folks have a nice tutorial to refer to when learning about the functionality, and some info on what's happening behind the resources when debugging is needed)

I know some of the functionality is indirectly demonstrated by proposed additions to heat-templates, but I think we probably need something in docs.openstack.org too.

[Steven Hardy (shardy)]

Few more observations having looked at some of the examples:

- Need to describe clearly the difference between Software* and Structured* resources
- Some documentation related to the hook scripts is needed
- The *Deployment "action" property description is unclear "Which actions the deployment will be triggered in.", it's not clear to me if this means we now have a hook which can be applied only on certain lifecycle/action transitions?

Overall I think we really need more very simple examples to provide an accessible introduction to folks not familiar with the new software config abstractions, combined with more detailed descriptions of the underlying interfaces and expected workflow.

[OpenStack Infra (hudson-openstack)]

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

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/81407
Committed: https://git.openstack.org/cgit/openstack/heat/commit/?id=66d701564cd467fa00e818fd87f3b1350ab9b622
Submitter: Jenkins
Branch: master

commit 66d701564cd467fa00e818fd87f3b1350ab9b622
Author: Steve Baker <email address hidden>
Date: Wed Mar 19 13:46:53 2014 +1300

    Document software config classes

    These doc descriptions are used in the generated reference for
    the template guide.

    Change-Id: I2dcd3c53b274777d172ed0464ad09befd85f8426
    Partial-Bug: #1294086

[Angus Salkeld (asalkeld)]

Just setting to Triaged as it's been in-progress for 1 year.

[Steven Hardy (shardy)]

Maybe we should just close this? When I raised it the docs were very sparse, but we now have a reasonable level of documentation in both the docstrings and heat-templates examples. There's also a pretty good section in the user guide:

http://docs.openstack.org/user-guide/content/software-deployment-resources.html

As the originator of the bug, I'm perfectly fine if we close it fix committed, unless there are specific gaps stevebaker still wishes to address via this bug.

[Steve Baker (steve-stevebaker)]

I think we can close it as fixed. More specific doc tasks can always be raised.