Improve Resources' classes docstrings
Current resources' description is poor, so need to write docstrings for resources with no description and expand existing docstring, if it's needed. implements bp docstring-improvements Change-Id: I3de1569904aaed4af4a7e7776b8c487db8736b0c
This commit is contained in:
Peter Razumovsky
parent
764c38b3f3
commit
ddba74ffea
|
|
@ -8,6 +8,7 @@ heat-specs Design Specifications
|
|||
specs/juno/*
|
||||
specs/kilo/*
|
||||
specs/liberty/*
|
||||
specs/mitaka/*
|
||||
|
||||
|
||||
heat-specs Repository Information
|
||||
|
|
|
|||
|
|
@ -0,0 +1,117 @@
|
|||
..
|
||||
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
||||
License.
|
||||
|
||||
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||
|
||||
=================================
|
||||
Resources docstrings improvements
|
||||
=================================
|
||||
|
||||
https://blueprints.launchpad.net/heat/+spec/docstring-improvements
|
||||
|
||||
Current Resources' descriptions are poor. Description of any resource
|
||||
get from resource's class docstring. So there is need to add docstring to
|
||||
resources, which have no description and fix existing relying on
|
||||
`PEP rules <http://legacy.python.org/dev/peps/pep-0008/>`_.
|
||||
|
||||
Problem description
|
||||
===================
|
||||
|
||||
Current Resources' descriptions are poor. It's means that new users cannot
|
||||
open documentation, learn for what this or that resource is needed and begin
|
||||
to use it. They have to search native documentation of resources. So,
|
||||
documentation *must* contains summary information about each resource that
|
||||
orchestration uses.
|
||||
|
||||
Besides that, some docstrings have template example, also template displays
|
||||
in documentation, so there are two template's entry for one resource. This
|
||||
situation should be fixed.
|
||||
|
||||
Proposed change
|
||||
===============
|
||||
|
||||
Solution of this problem includes next cases:
|
||||
|
||||
1. Fix all existing docstrings relying on
|
||||
`PEP rules <http://legacy.python.org/dev/peps/pep-0008/>`_. When this case
|
||||
will be done, need to remove ignorance of PEP8 rules in tox.ini file.
|
||||
|
||||
2. Add docstrings of next resources:
|
||||
|
||||
* OS::Barbican::* resources
|
||||
* OS::Ceilometer::* resources
|
||||
* OS::Cinder::Volume
|
||||
* OS::Cinder::VolumeAttachment
|
||||
* OS::Designate::* resources
|
||||
* 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::* resources
|
||||
* OS::Swift::Container
|
||||
* OS::Trove::Cluster
|
||||
* OS::Zaqar::Queue
|
||||
|
||||
3. Expand/fix docstrings of next resources:
|
||||
|
||||
* OS::Cinder::EncryptedVolumeType
|
||||
* OS::Cinder::VolumeType
|
||||
* OS::Glance::Image
|
||||
* OS::Heat::RandomString
|
||||
* OS::Heat::Stack
|
||||
* OS::Heat::ScalingPolicy
|
||||
* OS::Keystone::* resources
|
||||
* OS::Magnum::BayModel
|
||||
* OS::Manila::ShareNetwork
|
||||
* OS::Monasca::AlarmDefinition
|
||||
* OS::Monasca::Notification
|
||||
* OS::Neutron::* resources
|
||||
* OS::Nova::Flavor
|
||||
* OS::Nova::ServerGroup
|
||||
* OS::Trove::Instance
|
||||
|
||||
As additional issue, fix coding of internal templates, i.e. add tags for
|
||||
YAML code for colorization template.
|
||||
|
||||
Alternatives
|
||||
------------
|
||||
|
||||
None
|
||||
|
||||
Implementation
|
||||
==============
|
||||
|
||||
Assignee(s)
|
||||
-----------
|
||||
|
||||
Primary assignee:
|
||||
<prazumovsky>
|
||||
|
||||
Milestones
|
||||
----------
|
||||
|
||||
Target Milestone for completion:
|
||||
mitaka-1
|
||||
|
||||
Work Items
|
||||
----------
|
||||
|
||||
* Fix docstrings with PEP8 rules
|
||||
* Remove ignored rules from tox.ini
|
||||
* Add docstrings to Resource's classes where they omitted
|
||||
* Improve and fix docstring where it needed
|
||||
* Fix coding of internal templates
|
||||
|
||||
Dependencies
|
||||
============
|
||||
|
||||
None
|
||||
|
|
@ -0,0 +1,95 @@
|
|||
..
|
||||
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
||||
License.
|
||||
|
||||
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||
|
||||
..
|
||||
This template should be in ReSTructured text. The filename in the git
|
||||
repository should match the launchpad URL, for example a URL of
|
||||
https://blueprints.launchpad.net/heat/+spec/awesome-thing should be named
|
||||
awesome-thing.rst . Please do not delete any of the sections in this
|
||||
template. If you have nothing to say for a whole section, just write: None
|
||||
For help with syntax, see http://sphinx-doc.org/rest.html
|
||||
To test out your formatting, see http://www.tele3.cz/jbar/rest/rest.html
|
||||
|
||||
===========================
|
||||
The title of your blueprint
|
||||
===========================
|
||||
|
||||
Include the URL of your launchpad blueprint:
|
||||
|
||||
https://blueprints.launchpad.net/heat/+spec/example
|
||||
|
||||
Introduction paragraph -- why are we doing anything?
|
||||
|
||||
Problem description
|
||||
===================
|
||||
|
||||
A detailed description of the problem.
|
||||
|
||||
Proposed change
|
||||
===============
|
||||
|
||||
Here is where you cover the change you propose to make in detail. How do you
|
||||
propose to solve this problem?
|
||||
|
||||
If this is one part of a larger effort make it clear where this piece ends. In
|
||||
other words, what's the scope of this effort?
|
||||
|
||||
Include where in the heat tree hierarchy this will reside.
|
||||
|
||||
If your specification proposes any changes to the Heat REST API such
|
||||
as changing parameters which can be returned or accepted, or even
|
||||
the semantics of what happens when a client calls into the API, then
|
||||
you should add the APIImpact flag to the commit message. Specifications with
|
||||
the APIImpact flag can be found with the following query:
|
||||
|
||||
https://review.openstack.org/#/q/status:open+project:openstack/heat-specs+message:apiimpact,n,z
|
||||
|
||||
Alternatives
|
||||
------------
|
||||
|
||||
This is an optional section, where it does apply we'd just like a demonstration
|
||||
that some thought has been put into why the proposed approach is the best one.
|
||||
|
||||
Implementation
|
||||
==============
|
||||
|
||||
Assignee(s)
|
||||
-----------
|
||||
|
||||
Who is leading the writing of the code? Or is this a blueprint where you're
|
||||
throwing it out there to see who picks it up?
|
||||
|
||||
If more than one person is working on the implementation, please designate the
|
||||
primary author and contact.
|
||||
|
||||
Primary assignee:
|
||||
<launchpad-id or None>
|
||||
|
||||
Can optionally can list additional ids if they intend on doing
|
||||
substantial implementation work on this blueprint.
|
||||
|
||||
Milestones
|
||||
----------
|
||||
|
||||
Target Milestone for completion:
|
||||
mitaka-1
|
||||
|
||||
Work Items
|
||||
----------
|
||||
|
||||
Work items or tasks -- break the feature up into the things that need to be
|
||||
done to implement it. Those parts might end up being done by different people,
|
||||
but we're mostly trying to understand the timeline for implementation.
|
||||
|
||||
|
||||
Dependencies
|
||||
============
|
||||
|
||||
- Include specific references to specs and/or blueprints in heat, or in other
|
||||
projects, that this one either depends on or is related to.
|
||||
|
||||
- Does this feature require any new library dependencies or code otherwise not
|
||||
included in OpenStack? Or does it depend on a specific version of library?
|
||||
Loading…
Reference in New Issue