资源文档字符串改进

https://blueprints.launchpad.net/heat/+spec/docstring-improvements

当前资源的描述信息不足。任何资源的描述都从资源的类文档字符串中获取。因此，需要为没有描述的资源添加文档字符串，并修复现有文档字符串，使其符合 PEP 规则。

问题描述

当前资源的描述信息不足。这意味着新用户无法打开文档，了解某个资源的作用以及如何使用它。他们不得不搜索资源的本机文档。因此，文档必须包含编排使用的每个资源的摘要信息。

此外，某些文档字符串包含模板示例，模板也会显示在文档中，因此一个资源有两个模板条目。这种情况应该修复。

提议的变更

解决此问题包括以下几个方面

1. 修复所有符合 PEP 规则 的现有文档字符串。完成此操作后，需要从 tox.ini 文件中删除忽略 PEP8 规则的设置。

2. 添加以下资源的文档字符串

   • OS::Barbican::* 资源

   • OS::Ceilometer::* 资源

   • OS::Cinder::Volume

   • OS::Cinder::VolumeAttachment

   • OS::Designate::* 资源

   • OS::Heat::AccessPolicy

   • OS::Heat::AutoScalingGroup

   • OS::Heat::InstanceGroup

   • OS::Heat::SwiftSignal

   • OS::Heat::SwiftSignalHandle

   • OS::Heat::WaitCondition

   • OS::Heat::WaitConditionHandle

   • OS::Mistral::CronTrigger

   • OS::Mistral::Workflow

   • OS::Nova::FloatingIP

   • OS::Nova::FloatingIPAssociation

   • OS::Nova::Server

   • OS::Sahara::* 资源

   • OS::Swift::Container

   • OS::Trove::Cluster

   • OS::Zaqar::Queue

3. 扩展/修复以下资源的文档字符串

   • OS::Cinder::EncryptedVolumeType

   • OS::Cinder::VolumeType

   • OS::Glance::Image

   • OS::Heat::RandomString

   • OS::Heat::Stack

   • OS::Heat::ScalingPolicy

   • OS::Keystone::* 资源

   • OS::Magnum::BayModel

   • OS::Manila::ShareNetwork

   • OS::Monasca::AlarmDefinition

   • OS::Monasca::Notification

   • OS::Neutron::* 资源

   • OS::Nova::Flavor

   • OS::Nova::ServerGroup

   • OS::Trove::Instance

作为附加问题，修复内部模板的编码，例如，为 YAML 代码添加标签以进行模板颜色化。

备选方案

无

实现

负责人

主要负责人

<prazumovsky>

里程碑

完成目标里程碑

mitaka-1

工作项

• 修复符合 PEP8 规则的文档字符串

• 从 tox.ini 中删除忽略的规则

• 为省略了文档字符串的资源类添加文档字符串

• 改进和修复需要的文档字符串

• 修复内部模板的编码

依赖项

无