Add rst heading definitions

- Add licensing headers
- Add definitions for heading markup
- Update rst files to conform to the heading definitions

Change-Id: I75a9b29dbe9b3160cd682defa79ef6a02193de04
Closes-Bug: #1673530

CONTRIBUTING.rst

@@ -1,3 +1,26 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+      Convention for heading levels in collectd-ceilometer-plugin documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
+=========================
 Contributing to Openstack
 =========================
 
@@ -20,19 +43,19 @@ Bugs should be filed on Launchpad, not GitHub:
    https://bugs.launchpad.net/collectd-ceilometer-plugin
 
 Contributing to collectd-ceilometer-plugin
-==========================================
+------------------------------------------
 
 As well as following the OpenStack contribution guidelines, there are a few
 guidelines that should be observed for this project.
 
 Blueprints
-----------
+~~~~~~~~~~
 Blueprints are generally not required for features. A bug should be opened in
 launchpad instead and tagged as "rfe".
 
 
 Feature development
--------------------
+~~~~~~~~~~~~~~~~~~~
 Each feature should consist of a number of components (below), which can be submitted
 in separate, dependant patches.
 
@@ -67,7 +90,7 @@ The patches should include the following:
 
 
 Bug Fixes
----------
+~~~~~~~~~
 A bug fix will typically be a single patch, with any relevant changes to
 documantation, configuration, etc included.
 

HACKING.rst

@@ -1,4 +1,27 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+      Convention for heading levels in collectd-ceilometer-plugin documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
+=============================================
 collectd-ceilometer-plugin Style Commandments
-===============================================
+=============================================
 
 Read the OpenStack Style Commandments http://docs.openstack.org/developer/hacking/

README.rst

@@ -1,6 +1,28 @@
-===============================
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+      Convention for heading levels in collectd-ceilometer-plugin documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
+==========================
 collectd-ceilometer-plugin
-===============================
+==========================
 
 OpenStack Ceilometer plugin for collectd.
 

doc/source/GSG.rst

@@ -1,3 +1,26 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in collectd-ceilometer-plugin documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
 =============================
 Getting Started with Collectd
 =============================
@@ -12,11 +35,8 @@ Pre-requisites
 - A working Openstack environment
 - Keystone and Ceilometer services enabled
 
-Linux Configuration
--------------------
-
 Collectd Set-up
-===============
+---------------
 
 Ensure that the binary packages for your Linux distribution are installed
 and up-to-date.
@@ -52,7 +72,7 @@ Now, install collectd.
 | sudo make install
 
 Set and Configure Collectd as a Service
-=======================================
+---------------------------------------
 
 To enable collectd as a service on your system copy the .service onto your
 system. This file is located in the "/collectd/contrib/" directory of the repo.
@@ -72,7 +92,7 @@ For further information on enabling collectd as a service:
  https://collectd.org/wiki/index.php/First_steps#Starting_the_daemon
 
 Installation and Configuration of collectd-ceilometer-plugin
-============================================================
+------------------------------------------------------------
 
 Clone the collectd-ceilometer-plugin code.
 
@@ -139,10 +159,10 @@ To verify that ceilometer is working with collectd use the ceilometer client.
   |  ceilometer sample-list --meter cpu.cpu
 
 Additional Features
-===================
+-------------------
 
 Customized Units
-----------------
+~~~~~~~~~~~~~~~~
 
 This feature enables you to customize the units of the data being collected. It
 can be used to update existing units or add in new units by updating the plugin
@@ -175,7 +195,7 @@ or the sample-list and check the units of the meter that you changed.
 | ceilometer sample-list | grep <meter_name>
 
 Troubleshooting
-===============
+---------------
 
 If you are unable to verify that ceilometer is working with collectd, try
 restarting the service, then check the meter list again.

doc/source/contributing.rst

@@ -1,3 +1,26 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in collectd-ceilometer-plugin documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
 ============
 Contributing
 ============

doc/source/devstackGSG.rst

@@ -1,3 +1,26 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in collectd-ceilometer-plugin documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
 ===================================================
 Installing Collectd-ceilometer-plugin with Devstack
 ===================================================
@@ -11,7 +34,7 @@ Pre-requisites
 - Access to the internet
 
 Installation of Devstack
-========================
+------------------------
 
 Follow the instructions provided in the following document to set up your own
 Devstack deployment.
@@ -22,7 +45,7 @@ Once Devstack is ready to be deployed, follow the configuration steps in the
 next section to allow the installation of the plugin during deployment.
 
 Configuration of Devstack
-=========================
+-------------------------
 
 These configuration instructions only allow for the minimal installation of
 collectd, ceilometer and the plugin. The sample local.conf provided must be
@@ -47,7 +70,7 @@ Finally, build your devstack environment.
 | ./stack.sh
 
 Verfication of Collectd-ceilometer-plugin
-=========================================
+-----------------------------------------
 
 Confirm that the collectd service is up and running.
 
@@ -60,10 +83,10 @@ working with ceilometer.
 | ceilometer sample-list --meter cpu.cpu
 
 Addtional Features
-==================
+------------------
 
 Custom Units Feature
---------------------
+~~~~~~~~~~~~~~~~~~~~
 
 This feature enables users to define new units for existing meter values.
 To enable this feature execute the following instructions:
@@ -79,7 +102,7 @@ To enable this feature execute the following instructions:
 | COLLECTD_CUSTOM_UNITS="<meter> <unit>,<meter> <unit>"
 
 Gnocchi
-=======
+-------
 
 To deploy with gnocchi using devstack, add the following to you local.conf:
 

doc/source/index.rst

@@ -1,10 +1,29 @@
-.. collectd-ceilometer-plugin documentation master file, created by
+..
-   sphinx-quickstart on Tue Jul  9 22:26:36 2013.
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
-   You can adapt this file completely to your liking, but it should at least
+      not use this file except in compliance with the License. You may obtain
-   contain the root `toctree` directive.
+      a copy of the License at
 
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in collectd-ceilometer-plugin documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
+======================================================
 Welcome to collectd-ceilometer-plugin's documentation!
-========================================================
+======================================================
 
 Contents:
 
@@ -17,7 +36,7 @@ Contents:
    contributing
 
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`

doc/source/readme.rst

@@ -1 +1,27 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in collectd-ceilometer-plugin documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
+======
+README
+======
 .. include:: ../../README.rst

doc/source/troubleshooting.rst

@@ -1,3 +1,27 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in collectd-ceilometer-plugin documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
+================================================
 collectd-ceilometer-plugin troubleshooting guide
 ================================================
 

doc/source/usage.rst

@@ -1,3 +1,26 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in collectd-ceilometer-plugin documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
 =====
 Usage
 =====
@@ -152,7 +175,7 @@ COLLECTD_PREFIX
 
 
 Authenticating using Identity Server API v3
-===========================================
+-------------------------------------------
 
 following environment variables are used in this plugin for authentication
 to Keystone API v3

doc/source/vagrant.rst

@@ -1,3 +1,26 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in collectd-ceilometer-plugin documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
 =======
 Vagrant
 =======

kolla/installation.rst

@@ -1,17 +1,41 @@
-Introduction
+..
-============
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in networking-ovs-dpdk documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
+===============================================
+Deploying collectd-ceilometer-plugin with Kolla
+===============================================
 
 This document describes the steps required to install, configure and verify the
 operation of collectd with ceilometer plugin with Kolla.
 
 Pre-requisites
-==============
+--------------
 
 - Access to the internet
 - Keystaone and Ceilometer enabled
 
 Installation of Kolla
-=====================
+---------------------
 
 Please refer to this doc for instructions about how to install kolla.
 
@@ -21,7 +45,7 @@ For the simplest installation follow the instructions for evaluation and
 development purposes.
 
 Install Collectd with Kolla
-===========================
+---------------------------
 
 To install collectd with kolla, edit the ``globals.yml`` file and change the
 following settings:
@@ -70,7 +94,7 @@ Run the following command to build the container.
     kolla-build --template-override <path_to_template_override_file>
 
 Verification of Collectd
-========================
+------------------------
 
 To verify the successful build of the collectd image run the following command.
 
@@ -89,7 +113,7 @@ is up and running.
 The status of the collectd container should be "Up".
 
 Configure collectd-ceilometer-plugin
-====================================
+------------------------------------
 
 Edit the ``/kolla/etc/collectd-ceilometer-plugin.conf`` file and replace the
 varaiables with appropriate values. The passwords and endpoints will be
@@ -125,7 +149,7 @@ Restart the collectd container for the changes to take affect.
 Verify the container is up and running.
 
 Verification of collectd-ceilometer-plugin
-==========================================
+------------------------------------------
 
 To verify that the plugin is working, use the ceilometer client.
 

releasenotes/notes/bug-1673530-5d7789cacf4bc925.yaml

@@ -0,0 +1,5 @@
+---
+other:
+  - |
+    Fixes `bug 1673530`_: Added headers to usage.rst to allow linking to
+    configuration option descriptions in usage.rst.