diff --git a/doc/source/plugins.rst b/doc/source/plugins.rst
index 7a47b2678b..31862b0f37 100644
--- a/doc/source/plugins.rst
+++ b/doc/source/plugins.rst
@@ -24,7 +24,7 @@ plugin for Ceilometer if you wish to instrument a measurement which
 has not yet been covered by an existing plugin.
 
 Agents
-======
+~~~~~~
 
 Polling agent might be run either on central cloud management nodes or on the
 compute nodes (where direct hypervisor polling is quite logical).
@@ -39,13 +39,13 @@ The agent running on the cloud central management node polls other types of
 resources from a management server (usually using OpenStack services API to
 collect this data).
 
-The polling agent is implemented in ``ceilometer/agent/manager.py``. As
+The polling agent is implemented in :file:`ceilometer/agent/manager.py`. As
 you will see in the manager, the agent loads all plugins defined in
 the namespace ``ceilometer.poll.agent``, then periodically calls their
 :func:`get_samples` method.
 
 Plugins
-=======
+~~~~~~~
 
 A polling agent can support multiple plugins to retrieve different
 information and send them to the collector. As stated above, an agent
@@ -75,18 +75,18 @@ Pollster
 
 Compute plugins are defined as subclasses of the
 :class:`ceilometer.compute.pollsters.BaseComputePollster` class as defined in
-the ``ceilometer/compute/pollsters/__init__.py`` file. Pollsters must implement
-one method: ``get_samples(self, manager, cache, resources)``, which returns a
-sequence of ``Sample`` objects as defined in the
-``ceilometer/sample.py`` file.
+the :file:`ceilometer/compute/pollsters/__init__.py` file. Pollsters must
+implement one method: ``get_samples(self, manager, cache, resources)``, which
+returns a sequence of ``Sample`` objects as defined in the
+:file:`ceilometer/sample.py` file.
 
 In the ``CPUPollster`` plugin, the ``get_samples`` method is implemented as a
 loop which, for each instances running on the local host, retrieves the
 cpu_time from the hypervisor and sends back two ``Sample`` objects.  The first
-one, named "cpu", is of type "cumulative", meaning that between two polls, its
-value is not reset while the instance remains active, or in other words that
-the CPU value is always provided as a duration that continuously increases
-since the creation of the instance. The second one, named "cpu_util", is of
+one, named ``cpu``, is of type "cumulative", meaning that between two polls,
+its value is not reset while the instance remains active, or in other words
+that the CPU value is always provided as a duration that continuously increases
+since the creation of the instance. The second one, named ``cpu_util``, is of
 type "gauge", meaning that its value is the percentage of cpu utilization.
 
 Note that the ``LOG`` method is only used as a debugging tool and does not
@@ -94,13 +94,13 @@ participate in the actual metering activity.
 
 There is the way to specify either namespace(s) with pollsters or just
 list of concrete pollsters to use, or even both of these parameters on the
-polling agent start via CLI parameter:
+polling agent start via CLI parameter::
 
     ceilometer-polling --polling-namespaces central compute
 
 This command will basically make polling agent to load all plugins from the
 central and compute namespaces and poll everything it can. If you need to load
-only some of the pollsters, you can use ``pollster-list`` option:
+only some of the pollsters, you can use ``pollster-list`` option::
 
     ceilometer-polling --pollster-list image image.size storage.*
 
@@ -126,9 +126,13 @@ Notifications are defined as subclass of the
 :class:`ceilometer.agent.plugin_base.NotificationBase` meta class.
 Notifications must implement:
 
-   ``event_types`` which should be a sequence of strings defining the event types to be given to the plugin and
+   ``event_types``
+      A sequence of strings defining the event types to be given to the plugin
 
-   ``process_notification(self, message)`` which receives an event message from the list provided to event_types and returns a sequence of Sample objects as defined in the ``ceilometer/sample.py`` file.
+   ``process_notification(self, message)`` 
+      Receives an event message from the list provided to ``event_types`` and
+      returns a sequence of ``Sample`` objects as defined in the
+      :file:`ceilometer/sample.py` file.
 
 In the ``InstanceNotifications`` plugin, it listens to three events:
 
@@ -138,7 +142,7 @@ In the ``InstanceNotifications`` plugin, it listens to three events:
 
 * compute.instance.delete.start
 
-using the ``get_event_type`` method and subsequently the method
+Using the ``get_event_type`` method and subsequently the method
 ``process_notification`` will be invoked each time such events are happening which
 generates the appropriate sample objects to be sent to the collector.
 
@@ -152,7 +156,7 @@ needs to be easy to extend and configure so it can be tuned for each
 installation. A plugin system based on `setuptools entry points`_
 makes it easy to add new monitors in the agents.  In particular,
 Ceilometer now uses Stevedore_, and you should put your entry point
-definitions in the ``entry_points.txt`` file of your Ceilometer egg.
+definitions in the :file:`entry_points.txt` file of your Ceilometer egg.
 
 .. _setuptools entry points: http://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins
 
@@ -161,17 +165,18 @@ definitions in the ``entry_points.txt`` file of your Ceilometer egg.
 Installing a plugin automatically activates it the next time the
 ceilometer daemon starts. Rather than running and reporting errors or
 simply consuming cycles for no-ops, plugins may disable themselves at
-runtime based on configuration settings defined by other components (for example, the
-plugin for polling libvirt does not run if it sees that the system is
-configured using some other virtualization tool). Additionally, if no
+runtime based on configuration settings defined by other components (for
+example, the plugin for polling libvirt does not run if it sees that the system
+is configured using some other virtualization tool). Additionally, if no
 valid resources can be discovered the plugin will be disabled.
 
 
 Tests
-=====
+~~~~~
+
 Any new plugin or agent contribution will only be accepted into the project if
 provided together with unit tests.  Those are defined for the compute agent
-plugins in the directory ``tests/compute`` and for the agent itself in ``test/agent``.
-Unit tests are run in a continuous integration process for each commit made to
-the project, thus ensuring as best as possible that a given patch has no side
-effect to the rest of the project.
+plugins in the directory ``tests/compute`` and for the agent itself in
+``test/agent``. Unit tests are run in a continuous integration process for
+each commit made to the project, thus ensuring as best as possible that a given
+patch has no side effect to the rest of the project.