doc: Clean up for 0.0.2

projectatomic · Feb 27, 2017 · eeafc34 · eeafc34
1 parent d324816
commit eeafc34
Show file tree

Hide file tree

Showing 12 changed files with 179 additions and 234 deletions.
diff --git a/INSTALL.md → DEVEL.rst b/INSTALL.md → DEVEL.rst
@@ -90,7 +90,7 @@ cp conf/commissaire.conf config.conf
 ```
 Note: if locally installed you do not need to change anything
 
-Start the service 
+Start the service
 ```
 commissaire-server -c config.conf &
 popd

diff --git a/doc/commctl.rst b/doc/commctl.rst
@@ -8,13 +8,10 @@ Preface
 
 .. _commctl_preface:
 
-.. todo::
-
-    Give a fuller description.
-
-``commctl`` is the official command line utility for Commissaire.
+``commctl`` is the official command line utility for Commissaire. ``commctl`` acts as
+a clean user interface between the operator and the commissaire-server allowing for a
+more traditional experience for operators.
 
-.. include:: examples/commctl_note.rst
 
 Installation
 ------------
@@ -31,9 +28,8 @@ Via Source
 Via Docker
 ~~~~~~~~~~
 
-.. todo::
+.. include:: examples/commctl_install_docker.rst
 
-    TODO
 
 Via RPM
 ~~~~~~~
@@ -159,10 +155,6 @@ To list all clusters:
 deploy start
 ````````````
 
-.. todo::
-
-    Currently not ported to new architecture.
-
 ``deploy start`` will create a new deployment on an Atomic Host. This is an
 asynchronous action. See :ref:`deploy_status` on checking the results.
 
@@ -182,10 +174,6 @@ asynchronous action. See :ref:`deploy_status` on checking the results.
 deploy status
 `````````````
 
-.. todo::
-
-    Currently not ported to new architecture.
-
 ``deploy status`` will retrieve the status of an deploy
 
 ``deploy status`` requires one positional argument:
@@ -200,10 +188,6 @@ deploy status
 restart start
 `````````````
 
-.. todo::
-
-    Currently not ported to new architecture.
-
 ``restart start`` will create a new restart roll on a cluster of hosts. This is an
 asynchronous action. See :ref:`restart_status` on checking the results.
 
@@ -220,10 +204,6 @@ asynchronous action. See :ref:`restart_status` on checking the results.
 restart status
 ``````````````
 
-.. todo::
-
-    Currently not ported to new architecture.
-
 ``restart status`` will retrieve the status of an restart
 
 ``restart status`` requires one positional argument:
@@ -236,10 +216,6 @@ restart status
 upgrade start
 `````````````
 
-.. todo::
-
-    Currently not ported to new architecture.
-
 ``upgrade start`` will create a new upgrade on a cluster of hosts. This is an
 asynchronous action. See :ref:`upgrade_status` on checking the results.
 
@@ -256,10 +232,6 @@ asynchronous action. See :ref:`upgrade_status` on checking the results.
 upgrade status
 ``````````````
 
-.. todo::
-
-    Currently not ported to new architecture.
-
 ``upgrade status`` will retrieve the status of an upgrade
 
 ``upgrade status`` requires one positional argument:

diff --git a/doc/components.rst b/doc/components.rst
@@ -5,15 +5,11 @@ Internal
 --------
 The following are internal components of commissaire.
 
-.. todo::
-
-    REST Interface -> commissaire-server
-
-REST Interface
-~~~~~~~~~~~~~~
-The rest interface is the way an administrator works with commissaire. It
-attempts to follow REST as strictly as possible through the interpretation of
-commissaire developers.
+Commissaire Server
+~~~~~~~~~~~~~~~~~~
+The commissaire server is the ``REST`` interface and is how an administrator works
+with commissaire. It attempts to follow ``REST`` as strictly as possible through
+the interpretation of commissaire developers.
 
 
 Services

diff --git a/doc/conf.py b/doc/conf.py
@@ -58,7 +58,7 @@
 
 # General information about the project.
 project = 'Commissaire'
-copyright = '2016, See CONTRIBUTORS'
+copyright = '2016 - 2007, See CONTRIBUTORS'
 author = 'See CONTRIBUTORS'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -68,7 +68,7 @@
 # The short X.Y version.
 version = '0.0'
 # The full version, including alpha/beta/rc tags.
-release = '0.0.2-alpha'
+release = '0.0.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

diff --git a/doc/development.rst b/doc/development.rst
@@ -8,21 +8,7 @@ https://github.com/projectatomic/commissaire.
 
 Development Setup
 -----------------
-
-.. todo::
-
-    Maybe reference INSTALL.md instead?
-
-You will want to set up a virtualenv to work with. This will keep from poluting
-your system with application only dependencies while you code.
-
-.. include:: examples/setup_virtualenv.rst
-
-.. note::
-
-   Any time you will be working on commissaire make sure to activate the virtualenv
-
-.. _vagrant:
+See `DEVEL.rst <https://github.com/projectatomic/commissaire-http/blob/master/DEVEL.rst>`_
 
 Vagrant
 -------
@@ -169,10 +155,6 @@ To run unit tests locally and see where your code stands:
 End-to-End/BDD Testing
 ``````````````````````
 
-.. todo::
-
-    Currently not ported to new architecture.
-
 commissaire uses `Behave <http://pythonhosted.org/behave/>`_ to execute
 end to end/BDD tests. You will need to have the following in your parent
 directory to properly be able to execute tests locally.

diff --git a/doc/endpoints.rst b/doc/endpoints.rst
@@ -2,11 +2,12 @@
 
 REST Endpoints
 ==============
+``REST`` stands for representational state transfer and is one of many ways to expose API's as a web service.  ``REST`` allows
+"requesting systems to access and manipulate textual representations of Web resources using a uniform and predefined set of
+stateless operations. [...] Using HTTP, as is most common, the kind of operations available include those predefined by the
+HTTP verbs ``GET``, ``POST``, ``PUT``, ``DELETE`` and so on." (`Wikipedia <https://en.wikipedia.org/wiki/Representational_state_transfer>`_)
 
-.. todo::
-
-    Give a quick blurb about REST.
-
+For more information on ``REST`` see the `original dissertation <http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm>`_.
 
 .. _cluster_op:
 
@@ -20,7 +21,7 @@ Cluster
 
 .. versionchanged:: 0.1.0
 
-   ``type`` has been removed in favor of ``cluster_manager``.
+   ``type`` has been removed in favor of ``container_manager``.
 
 GET
 ```
@@ -32,7 +33,7 @@ Retrieve the status of the cluster.
        "name": string,
        "status" string,
        "network": string,
-       "cluster_manager": str,
+       "container_manager": str,
        "hosts": {
            "total": int,
            "available": int,
@@ -50,7 +51,7 @@ Example
        "name": "mycluster",
        "status": "ok",
        "network": "default",
-       "cluster_manager": "prod_openshift",
+       "container_manager": "prod_openshift",
        "hosts": {
            "total": 3,
            "available": 2,
@@ -69,7 +70,7 @@ Creates a new cluster.
 .. code-block:: javascript
 
     {
-        "cluster_manager": string // (Optional) Name of the cluster manager to use
+        "container_manager": string // (Optional) Name of the container manager to use
         "network": string     // The name of the network
     }
 
@@ -80,7 +81,7 @@ Example
 .. code-block:: javascript
 
    {
-       "cluster_manager": "prod_openshift",
+       "container_manager": "prod_openshift",
        "network": "default"
    }
 
@@ -195,10 +196,6 @@ Example Response
 Cluster Operations: Deploy
 --------------------------
 
-.. todo::
-
-    Currently not ported to new architecture.
-
 **Endpoint**: /api/v0/cluster/{NAME}/deploy
 
 (Internal model name: ``ClusterDeploy``)
@@ -271,10 +268,6 @@ Example Response
 Cluster Operations: Upgrade
 ---------------------------
 
-.. todo::
-
-    Currently not ported to new architecture.
-
 **Endpoint**: /api/v0/cluster/{NAME}/upgrade
 
 (Internal model name: ``ClusterUpgrade``)
@@ -331,10 +324,6 @@ Example Response
 Cluster Operations: Restart
 ---------------------------
 
-.. todo::
-
-    Currently not ported to new architecture.
-
 **Endpoint**: /api/v0/cluster/{NAME}/restart
 
 (Internal model name: ``ClusterRestart``)

diff --git a/doc/examples/commctl_install_docker.rst b/doc/examples/commctl_install_docker.rst
@@ -0,0 +1,8 @@
+
+From a checkout of the ``commctl`` repository:
+
+.. code-block:: shell
+
+   $ sudo docker build -t commctl .  # Done once to build the image
+   ...
+   $ sudo docker run -t -i --volume=`pwd`/.commissaire.json:/root/.commissaire.json:Z commctl --help
diff --git a/doc/http.rst → doc/http_devel.rst b/doc/http.rst → doc/http_devel.rst
@@ -1,5 +1,5 @@
-Commissaire HTTP
-================
+Developing on Commissaire HTTP
+==============================
 
 Commissaire HTTP provides a multithreaded REST interface into Commissaire
 functionality. The server is broken up into 5 main parts: ``Router``,

diff --git a/doc/index.rst b/doc/index.rst
@@ -1,15 +1,6 @@
 Commissaire
 ===========
 
-.. warning::
-
-    Some of this documentation will be out of date while architectural changes
-    are worked on.
-
-.. todo::
-
-    Update the docs to reflect changes in ``0.0.2`` as development progresses.
-
 .. todo::
 
     The layout of documentation could use work. It doesn't flow all that well.
@@ -27,7 +18,6 @@ Contents:
    commctl
    components
    services
-   http
    enums
    endpoints
    community_meetings
@@ -40,6 +30,8 @@ Development
 
    development
    authentication_devel
+   services_devel
+   http_devel
    packaging
    cloud_init
    cpd

diff --git a/doc/operations.rst b/doc/operations.rst
@@ -3,9 +3,10 @@ Operations
 
 Preface
 -------
-All operations via commissaire are done via REST. While any HTTP client can
-be used, many users will feel more comfortable using :ref:`commctl <commctl_preface>`.
-
+All operations via Commissaire are done via ``REST``. ``REST`` calls are the
+prefered way to integrate with Commissaire. While any HTTP client can be used
+to directly interface with the ``REST`` server, many operators will feel more
+comfortable using :ref:`commctl <commctl_preface>`.
 
 
 curl
@@ -18,7 +19,7 @@ With curl this looks like:
    curl ... -u "USERNAME:PASSWORD" ...
 
 
-The proper headers must also be passed. Since all of the REST communication
+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``.
 
 .. code-block:: shell
@@ -63,13 +64,9 @@ For specifics on the endpoint see :ref:`host_op`
 Cluster Operations with curl
 ----------------------------
 
-.. todo::
-
-    Currently not ported to new architecture.
-
-.. todo::
+.. note::
 
-    Reference commctl docs since most users will likely use that rather than direct curl
+    Operators will probably want to use :ref:`commctl_cli`
 
 These operations are done across all hosts associated with a cluster.
 
@@ -80,7 +77,7 @@ cluster.
 
 .. include:: examples/create_restart.rst
 
-To check on a ``restart`` record, 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
@@ -95,7 +92,7 @@ cluster.
 
 .. include:: examples/create_upgrade.rst
 
-To check on an ``upgrade`` record, 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
@@ -109,7 +106,7 @@ cluster.
 
 .. include:: examples/create_deploy.rst
 
-To check on a ``deploy`` record, 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