Fix doc gate job false success

pbr config was missing from setup.cfg. With adding "warnerrors = true"
under '[pbr]' in setup.cfg, the Sphinx build will fail in case of
warnings and errors during the build process.

This patch also fixes the currently existing problems in the developer
documentation of Ceilometer. The unused todo extension was also removed.

Fixes-Bug: #1317648
Fixes-Bug: #1321193
Fixes-Bug: #1272845

Change-Id: If1a9d7aca5c1d350568a83fb49bb8ea3defefdca

doc/source/api/index.rst

@@ -1,8 +0,0 @@
-======================
-Internal API Reference
-======================
-
-.. toctree::
-   :maxdepth: 1
-
-   autoindex

doc/source/architecture.rst

@@ -47,15 +47,9 @@ Metering
 If you divide a billing process into a 3 step process, as is commonly done in
 the telco industry, the steps are:
 
-1. :term:`Metering` is the process of collecting information about what,
+1. :term:`Metering`
-   who, when and how much regarding anything that can be billed. The result of
+2. :term:`Rating`
-   this is a collection of "tickets" (a.k.a. samples) which are ready to be
+3. :term:`Billing`
-   processed in any way you want.
-2. :term:`Rating` is the process of analysing a series of tickets,
-   according to business rules defined by marketing, in order to transform
-   them into bill line items with a currency value.
-3. :term:`Billing` is the process to assemble bill line items into a
-   single per customer bill, emitting the bill to start the payment collection.
 
 Ceilometer's initial goal was, and still is, strictly limited to step
 one. This is a choice made from the beginning not to go into rating or billing,

doc/source/conf.py

@@ -143,7 +143,6 @@ write_autodoc_index()
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
-    'sphinx.ext.todo',
     'sphinxcontrib.autohttp.flask',
     'wsmeext.sphinxext',
     'sphinx.ext.coverage',
@@ -252,7 +251,7 @@ html_theme_options = {
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+#html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.

doc/source/contributing/index.rst

@@ -24,4 +24,3 @@
    areas
    source
    plugins
-   ../api/index

doc/source/glossary.rst

@@ -30,6 +30,15 @@
    API server
      HTTP REST API service for ceilometer.
 
+   billing
+     Billing is the process to assemble bill line items into a single
+     per customer bill, emitting the bill to start the payment collection.
+
+   bus listener agent
+     Bus listener agent which takes events generated on the Oslo
+     notification bus and transforms them into Ceilometer samples. This
+     is the preferred method of data collection.
+
    ceilometer
      From Wikipedia [#]_:
 
@@ -55,21 +64,37 @@
    data store
      Storage system for recording data collected by ceilometer.
 
+   http callback
+     HTTP callback is used for calling a predefined URL, whenever an
+     alarm has been set off. The payload of the request contains
+     all the details of why the alarm was triggered.
+
+   log
+     Logging is one of the alarm actions that is useful mostly for debugging,
+     it stores the alarms in a log file.
+
    meter
      The measurements tracked for a resource. For example, an instance has
      a number of meters, such as duration of instance, CPU time used,
      number of disk io requests, etc.
      Three types of meters are defined in ceilometer:
-      * Cumulative: Increasing over time (e.g. disk I/O)
+
-      * Gauge: Discrete items (e.g. floating IPs, image uploads) and fluctuating
+       * Cumulative: Increasing over time (e.g. disk I/O)
-        values (e.g. number of Swift objects)
+       * Gauge: Discrete items (e.g. floating IPs, image uploads) and fluctuating
-      * Delta: Incremental change to a counter over time (e.g. bandwidth delta)
+         values (e.g. number of Swift objects)
+       * Delta: Incremental change to a counter over time (e.g. bandwidth delta)
+
+   metering
+     Metering is the process of collecting information about what,
+     who, when and how much regarding anything that can be billed. The result of
+     this is a collection of "tickets" (a.k.a. samples) which are ready to be
+     processed in any way you want.
 
    notification
-      A message sent via an external OpenStack system (e.g Nova, Glance,
+     A message sent via an external OpenStack system (e.g Nova, Glance,
-      etc) using the Oslo notification mechanism [#]_. These notifications
+     etc) using the Oslo notification mechanism [#]_. These notifications
-      are usually sent to and received by Ceilometer through the notifier
+     are usually sent to and received by Ceilometer through the notifier
-      RPC driver.
+     RPC driver.
 
    non-repudiable
     From Wikipedia [#]_:
@@ -84,6 +109,22 @@
    project
      The OpenStack tenant or project.
 
+   polling agents
+     The polling agent is collecting measurements by polling some API or other
+     tool at a regular interval.
+
+   push agents
+     The push agent is the only solution to fetch data within projects,
+     which do not expose the required data in a remotely usable way. This
+     is not the preferred method as it makes deployment a bit more
+     complex having to add a component to each of the nodes that need
+     to be monitored.
+
+   rating
+     Rating is the process of analysing a series of tickets,
+     according to business rules defined by marketing, in order to transform
+     them into bill line items with a currency value.
+
    resource
      The OpenStack entity being metered (e.g. instance, volume, image, etc).
 

doc/source/index.rst

@@ -17,7 +17,7 @@
 Welcome to the Ceilometer developer documentation!
 ==================================================
 
-The :term:`ceilometer` project aims to deliver a unique point of
+The :term:`Ceilometer` project aims to deliver a unique point of
 contact for billing systems to acquire all of the measurements they
 need to establish customer billing, across all current OpenStack core
 components with work underway to support future OpenStack components.
@@ -37,7 +37,7 @@ What is the purpose of the project and vision for it?
   users through a REST API.
 * The metering messages are signed and :term:`non-repudiable`.
 
-This documentation offers information on how ceilometer works and how to
+This documentation offers information on how Ceilometer works and how to
 contribute to the project.
 
 Table of contents
@@ -55,26 +55,7 @@ Table of contents
    contributing/index
    releasenotes/index
    glossary
-
+   sourcecode/autoindex
-.. - installation
-..   - devstack
-..   - take content from "initial setup"
-.. - configuration
-..   - talk about copying nova config file
-.. - running the services
-..   - agent on compute node
-..   - collector on controller (non-compute) node
-.. - contributing
-..   - joining the project (take this from another set of docs?)
-..   - reporting bugs
-..   - running tests
-..   - submitting patches for review
-.. - writing plugins
-..   - general plugin-based architecture information
-..     - reference to setuptools entry points docs
-..   - pollsters
-..   - notifications
-..   - database engine
 
 .. update index
 
@@ -84,8 +65,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-
-To Do
-=====
-
-.. todolist::

doc/source/install/mod_wsgi.rst

@@ -43,7 +43,7 @@ work with a copy of ceilometer installed via devstack.
    conflicts with Horizon's default configuration.
 
 3. Modify the ``WSGIDaemonProcess`` directive to set the
-  ``user`` and ``group`` values to a user available on your server.
+   ``user`` and ``group`` values to a user available on your server.
 
 4. Modify the ``APACHE_RUN_USER`` and ``APACHE_RUN_GROUP`` values to
    the name of a user and group available on your server.

doc/source/measurements.rst

@@ -114,11 +114,9 @@ or complete the existing ones.
 
 The meters below are related to the host machine.
 
-.. note::
+.. note:: By default, Nova will not collect the following meters related to the host
-
+   compute node machine. Nova option 'compute_monitors = ComputeDriverCPUMonitor'
-By default, Nova will not collect the following meters related to the host
+   should be set in nova.conf to enable meters.
-compute node machine. Nova option 'compute_monitors = ComputeDriverCPUMonitor'
-should be set in nova.conf to enable meters.
 
 ===============================  ==========  =========  ========  ============  ========================
 Name                             Type        Unit       Resource  Origin        Note

doc/source/releasenotes/folsom.rst

@@ -13,12 +13,14 @@
       License for the specific language governing permissions and limitations
       under the License.
 
+.. _folsom:
+
 ====================
-Version 0.1 (Folsom)
+Folsom
 ====================
 
-This is the first release of ceilometer. Please take all appropriate caution
+This is the first release (Version 0.1) of Ceilometer. Please take all appropriate
-in using it, as it is a technology preview at this time.
+caution in using it, as it is a technology preview at this time.
 
 Version of OpenStack
    It is curently tested to work with OpenStack 2012.2 Folsom. Due to its use of

doc/source/releasenotes/index.rst

@@ -18,5 +18,13 @@
 ============================
 
 .. toctree::
+   :hidden:
 
    folsom
+
+* :ref:`folsom`
+* `Havana`_
+* `Icehouse`_
+
+.. _Havana: https://wiki.openstack.org/wiki/ReleaseNotes/Havana#OpenStack_Metering_.28Ceilometer.29
+.. _IceHouse: https://wiki.openstack.org/wiki/ReleaseNotes/Icehouse#Ceilometer

setup.cfg

@@ -220,6 +220,9 @@ all_files = 1
 build-dir = doc/build
 source-dir = doc/source
 
+[pbr]
+warnerrors = true
+
 [extract_messages]
 keywords = _ gettext ngettext l_ lazy_gettext
 mapping_file = babel.cfg