docs: multiple small style tweaks (#46)

* docs: multiple small style tweaks

Just a collection of style changes I made while reading over the docs.

doc/commctl.rst

@@ -1,3 +1,4 @@
+.. _commctl_cli:
 
 commctl
 =======
@@ -73,7 +74,7 @@ The password may be stored in the configuration file as well.
 
 .. todo::
 
-    The kubernetes authentication plugin has not been ported yet.
+    The Kubernetes authentication plugin has not been ported yet.
 
 If you are using the :ref:`Kubernetes authentication plugin <kubeauth>` you can opt to reuse the credentials from your kubeconfig like so:
 
@@ -162,7 +163,7 @@ deploy start
 
     Currently not ported to new architecture.
 
-``deploy start`` will create a new deployment on an Atomic host. This is an
+``deploy start`` will create a new deployment on an Atomic Host. This is an
 asynchronous action. See :ref:`deploy_status` on checking the results.
 
 ``deploy start`` requires two positional arguments:

doc/components.rst

@@ -53,5 +53,5 @@ Kubernetes.
 Container Manager
 ~~~~~~~~~~~~~~~~~
 OpenShift or Kubernetes can be used as the container manager. commissaire utilizes
-Kubernetes api to ensure that new host nodes register properly. From this point
+Kubernetes API to ensure that new host nodes register properly. From this point
 forward Kubernetes is able to use the host node to schedule pods, etc...

doc/http.rst

@@ -3,12 +3,13 @@ Commissaire HTTP
 
 Commissaire HTTP provides a multithreaded REST interface into Commissaire
 functionality. The server is broken up into 5 main parts: ``Router``,
-``Dispatcher``, ``handlers``, and the ``CommissaireHttpServer`` itself.
+``Dispatcher``, ``Function Handler``, ``Class Handler``, and the
+``CommissaireHttpServer`` itself.
 
 Router
 ------
 The ``Router`` maps URI paths to controllers. The following example would route
-the path /hello/ to the controller at ``commissaire_http.handlers.hello_world``
+the path ``/hello/`` to the controller at ``commissaire_http.handlers.hello_world``
 if the HTTP method is ``GET``.
 
 .. todo::
@@ -54,12 +55,12 @@ convention so the ``Dispatcher`` knows it's valid during loading.
 
 Function Handler
 ````````````````
-Function handlers must take two parameters: ``message`` and ``bus``. The first
+Function Handlers must take two parameters: ``message`` and ``bus``. The first
 input, ``message``, is the jsonrpc message. The second input, ``bus`` will
 either be a valid connection to the bus or, if the bus is not enabled,
 ``None``.
 
-When referencing a function handler as a controller use the full package path
+When referencing a Function Handler as a controller use the full package path
 to the function. If the function is ``hello_world`` and it lives under
 ``commissaire_http.handlers`` then the controller would be
 ``commissaire_http.handlers.hello_world``.
@@ -97,22 +98,23 @@ the handler must be a valid jsonrpc message as well!
 
 Class Handler
 `````````````
-A class handler is not much different than function handlers. Instead of
+A Class Handler is not much different than a Function Handler. Instead of
 defining a single function, a class is declared with methods that take three
 parameters: ``self``, ``message``, and ``bus``. If the method should not be
 considered a handler it must start with an underscore.
 
-One major difference between a class handler and function handler is that class
-handlers are instantiated when they are loaded!
+One major difference between a Class Handler and Function Handler is that Class
+Handlers are instantiated when they are loaded!
 
-When referencing a class handler as a controller, use the full package path
+
+When referencing a Class Handler as a controller, use the full package path
 to the class and the method. If the class is ``ClassHandlerExample``,
 the method is ``hello``, and it lives under ``commissaire_http.handlers``
 then the controller would be
 ``commissaire_http.handlers.ClassHandlerExample.hello``.
 
-The following example exposes ``hello`` in the same way as the above function
-handler. It then uses ``hello_world`` to do the heavy lifting.
+The following example exposes ``hello`` in the same way as the Function
+Handler example above. It then uses ``hello_world`` to do the heavy lifting.
 
 .. code-block:: python
 
@@ -144,8 +146,8 @@ handler. It then uses ``hello_world`` to do the heavy lifting.
 CommissaireHttpServer
 ---------------------
 
-In the following example a ``CommissaireHttpServer`` is created which binds to
-address 127.0.0.1 and port 8000 and uses a previously created dispatcher. It
+In the following example, a ``CommissaireHttpServer`` is created which binds to
+address 127.0.0.1 and port 8000 and uses a previously created ``Dispatcher``. It
 then is set to run (block) until killed.
 
 .. code-block:: python

doc/index.rst

@@ -23,7 +23,6 @@ Contents:
    overview
    operations
    commctl
-   logging
    components
    services
    http

doc/operations.rst

@@ -19,7 +19,7 @@ With curl this looks like:
 
 
 The proper headers must also be passed. Since all of the REST communication
-is done via JSON the content-type must be set to application/json.
+is done via JSON the ``Content-Type`` must be set to ``application/json``.
 
 .. code-block:: shell
 
@@ -69,49 +69,49 @@ Cluster Operations with curl
 
 .. todo::
 
-    Reference commctl docs since most users will likely rather than than direct curl
+    Reference commctl docs since most users will likely use that rather than direct curl
 
 These operations are done across all hosts associated with a cluster.
 
 Restart
 ~~~~~~~
-Restarting a cluster is done by creating a new restart record for a specific
+Restarting a cluster is done by creating a new ``restart`` record for a specific
 cluster.
 
 .. include:: examples/create_restart.rst
 
-To check up on a restart a REST *GET* call on the same endpoint will show the
+To check on a ``restart`` record, a REST *GET* call on the same endpoint will show the
 current status.
 
 .. include:: examples/get_restart.rst
 
-For specifics on the endpoint see :ref:`cluster_op_restart`
+For specifics on the ``restart`` endpoint see :ref:`cluster_op_restart`
 
 
 Upgrade
 ~~~~~~~
-Upgrading a cluster is done by creating a new upgrade record for a specific
+Upgrading a cluster is done by creating a new ``upgrade`` record for a specific
 cluster.
 
 .. include:: examples/create_upgrade.rst
 
-To check up on an upgrade a REST *GET* call on the same endpoint will show the
+To check on an ``upgrade`` record, a REST *GET* call on the same endpoint will show the
 current status.
 
 .. include:: examples/get_upgrade.rst
 
-For specifics on the endpoint see :ref:`cluster_op_upgrade`
+For specifics on the ``upgrade`` endpoint see :ref:`cluster_op_upgrade`
 
 Deploy
 ~~~~~~
-Deploying to a cluster is done by creating a new upgrade record for a specific
+Deploying to a cluster is done by creating a new ``deploy`` record for a specific
 cluster.
 
 .. include:: examples/create_deploy.rst
 
-To check up on a deploy a REST *GET* call on the same endpoint will show the
+To check on a ``deploy`` record, a REST *GET* call on the same endpoint will show the
 current status.
 
 .. include:: examples/get_deploy.rst
 
-For specifics on the endpoint see :ref:`cluster_op_deploy`
+For specifics on the ``deploy`` endpoint see :ref:`cluster_op_deploy`

doc/overview.rst

@@ -7,7 +7,11 @@ Overview
 
    -- Ryan Cook
 
-commissaire is a lightweight REST interface for upgrading, restarting, and bootstrapping new hosts into an existing Container Management cluster such as OpenShift or Kubernetes.
+commissaire is a lightweight REST interface for upgrading, restarting, and bootstrapping new hosts into an existing Container Management cluster such as OpenShift_ or Kubernetes_.
+
+.. _Kubernetes: http://kubernetes.io
+
+.. _OpenShift: https://www.openshift.com
 
 Feature Overview
 ----------------
@@ -18,9 +22,9 @@ Feature Overview
 - No agent required for hosts: All communication is done over SSH
 - :ref:`Simple REST interface for automation <rest_endpoints>`
 - Service status for health checking
-- Plug-in based authentication framework
-- :ref:`Command line interface for operators <cluster_operations_with_commctl>`
-- :ref:`Built in support for Atomic, RHEL, Fedora, and CentOS <tested_host_node_oss>`
+- :ref:`Plug-in based authentication framework <authdevel>`
+- :ref:`Command line interface for operators <commctl_cli>`
+- Built in support for Atomic Host and Server variants of RHEL, Fedora, and CentOS
 
 
 Logical Flow
@@ -35,9 +39,12 @@ There are a lot of overloaded words in technology. It's important to note what
 commissaire is not as much as what it is. commissaire is not:
 
 - A Container Manager or scheduler (such as OpenShift or Kubernetes)
-- A configuration management system (such as ansible or puppet)
+- A configuration management system (such as Ansible_ or Puppet_)
 - A replacement for individual host management systems
 
+.. _Ansible: https://www.ansible.com
+
+.. _Puppet: https://puppet.com
 
 Example Uses
 ------------
@@ -50,7 +57,7 @@ Example Uses
 
    This is an early list. More use cases will be added in the future.
 
-- An administrator needs to upgrade an entire group of hosts acting as kubernetes nodes
-- An administrator needs to restart an entire group of hosts acting as kubernetes nodes
-- An organization would like new hosts to register themselves into a kubernetes cluster upon first boot without administrator intervention
-- An organization would like to keep groups of hosts used as kubernetes nodes out of direct control of anything but kubernetes and basic operations.
+- An administrator needs to upgrade an entire group of hosts acting as Kubernetes nodes
+- An administrator needs to restart an entire group of hosts acting as Kubernetes nodes
+- An organization would like new hosts to register themselves into a Kubernetes cluster upon first boot without administrator intervention
+- An organization would like to keep groups of hosts used as Kubernetes nodes out of direct control of anything but Kubernetes and basic operations.