Merge "Documentation edits:"

doc/source/agent/writing_agent_plugin.rst

@@ -13,15 +13,20 @@
       License for the specific language governing permissions and limitations
       under the License.
 
-This documentation has for objective to give you some clues on how to write a
+This documentation gives you some clues on how to write a
 new agent or plugin for Ceilometer a to use if you wish to instrument a
 functionality which has not yet been covered by an existing one.
 
+An agent runs on each compute node to poll for resource usage. Each metric 
+collected is tagged with the resource ID (such as an instance) and the owner,
+including tenant and user IDs.The metrics are then reported to the collector
+via the message bus. More detailed information follows. 
+
 Agent
 =====
 There is currently only one agent defined for Ceilometer which can be found at: ``ceilometer/agent/``
 As you will see in the ``manager.py`` file, this agent will automatically load any
-plugin defined in the namesace ``ceilometer.poll.compute``.
+plugin defined in the namespace ``ceilometer.poll.compute``.
 
 Agents are added by implementing a new nova.manager.Manager class, in the same
 way it was done for the AgentManager for the compute agent in the file
@@ -63,9 +68,9 @@ value of 1.
 Note that the ``LOG`` method is only used as a debugging tool and does not
 participate in the actual metering activity.
 
-Notification
-------------
-Notifiications are defined as subclass of the ``ceilometer.plugin.NotificationBase``
+Notifications
+-------------
+Notifications are defined as subclass of the ``ceilometer.plugin.NotificationBase``
 meta class as defined in the ``ceilometer/plugin.py`` file.  Notifications must
 implement two methods:
 
@@ -95,5 +100,3 @@ the project, thus ensuring as best as possible that a given patch has no side
 effect to the rest of the project.
 
 ### FIXME: could not find a unit test for CPUPollster
-
-

doc/source/index.rst

@@ -17,7 +17,16 @@
 Welcome to the Ceilometer developer documentation!
 ==================================================
 
-The ceilometer project aims to deliver a unique point of contact for billing  systems to aquire all meters they need to establish customer billing,  accross all current and future OpenStack core components.
+The ceilometer project aims to deliver a unique point of contact for billing
+systems to acquire all meters they need to establish customer billing, across
+all current OpenStack core components with work underway to support future
+OpenStack components through plugin agents.
+
+A list of the current usage data that ceilometer will (eventually) listen for
+can be found at http://wiki.openstack.org/SystemUsageData. For a list of the
+planned meters, refer to http://wiki.openstack.org/EfficientMetering#Meters.
+
+A list of the additional usage data is tracked in the bug tracker at https://bugs.launchpad.net/ceilometer.
 
 What is the purpose of the project and vision for it?
 =====================================================
@@ -27,12 +36,12 @@ What is the purpose of the project and vision for it?
 * Data may be collected by monitoring notifications sent from existing services or by polling the infrastructure.
 * Allow deployers to configure the type of data collected to meet their operating requirements.
 * The data collected by the metering system is made visible to some users through a REST API.
-* The metering messages are signed and non repudiable (http://en.wikipedia.org/wiki/Non-repudiation)
+* The metering messages are signed and non-repudiable. (http://en.wikipedia.org/wiki/Non-repudiation)
 
-This documentation has for objective to give you some clues on how to contribute code to ceilometer.
+This documentation offers information on how to contribute code to ceilometer.
 
-Table of content
-================
+Table of contents
+=================
 
 .. toctree::
    :maxdepth: 1

doc/source/initial_setup.rst

@@ -13,34 +13,35 @@
       License for the specific language governing permissions and limitations
       under the License.
 
-Initial reading
-===============
+Initial setup
+=============
 
-If you are not yet familiar with ceilometer's architecture, it would
-be advisable that you start by reading the blueprint_ and more
-specifically the architecture_ which has been agreed on.
-
-.. _architecture: http://wiki.openstack.org/EfficientMetering/ArchitectureProposalV1
-
-.. _blueprint: http://wiki.openstack.org/EfficientMetering
+If you are not yet familiar with ceilometer's architecture, it would be
+advisable that you start by reading the blueprint at http://wiki.openstack.org/EfficientMetering, and more specifically the architecture which has been agreed on
+at: http://wiki.openstack.org/EfficientMetering/ArchitectureProposalV1.
 
 In order to contribute to the ceilometer project, you will also need to:
 
-1. Have signed openstack's contributor's agreement
-    http://wiki.openstack.org/CLA
+1. Have signed OpenStack's contributor's agreement. Refer to http://wiki.openstack.org/CLA for more information.
 
-2. Be familiar with git and the OpenStack gerrit review process
-    http://wiki.openstack.org/GerritWorkflow
+2. Be familiar with git and the OpenStack Gerrit review process, see http://wiki.openstack.org/GerritWorkflow. 
+
+.. note:: 
+
+	Currently the ceilometer project is using StackForge, a
+	system for code reviews identical to the OpenStack contribution infrastructure. 
 
 Setting up the project
 ======================
 
-1. The first thing you will need to do is to clone the ceilometer project on your local machine:
+1. The first thing you will need to do is to clone the ceilometer project on your local machine::
+
     git clone https://github.com/stackforge/ceilometer.git
 
-2. Once this is done, you need to setup the review process:
+2. Once this is done, you need to setup the review process::
+
     git remote add gerrit ssh://<username>@review.stackforge.org:29418/stackforge/ceilometer.git
 
-3. Create a topic branch and switch to it
-    git checkout -b TOPIC-BRANCH
+3. Create a topic branch and switch to it::
 
+    git checkout -b TOPIC-BRANCH