Merge pull request #21 from Intelworks/doc-edits

initial edit

docs/developer.rst

@@ -8,19 +8,19 @@ Contributing and developing
 Reporting issues
 ================
 
-cabby uses Github's issue tracker. See the `cabby project page`_ on Github.
+Cabby uses Github's issue tracker. See the `Cabby project page`_ on Github.
 
 
 Obtaining the source code
 =========================
 
-The cabby source code can be found on Github. See the `cabby project page`_ on
+The Cabby source code can be found on Github. See the `Cabby project page`_ on
 Github.
 
 Layout
 ======
 
-The opentaxii repository has the following layout:
+The Cabby repository has the following layout:
 
 * ``docs/`` - used to build the `documentation <http://cabby.readthedocs.org>`_;
 * ``cabby/`` - source code;
@@ -38,7 +38,7 @@ After cloning the Github repo, just run::
 Running the tests
 =================
 
-Almost all cabby code is covered by the unit tests. cabby uses `py.test <http://pytest.org/latest/>`_ and
+Almost all Cabby code is covered by the unit tests. Cabby uses `py.test <http://pytest.org/latest/>`_ and
 `tox <http://tox.readthedocs.org/en/latest/>`_ for running tests. Type ``tox -r`` or ``py.test`` to run the unit tests.
 
 

docs/index.rst

@@ -4,22 +4,22 @@ Cabby
 
 Cabby is Python TAXII client implementation from Intelworks.
 
-Cabby's key features are:
+TAXII (Trusted Automated eXchange of Indicator Information) is a collection of specifications defining a set of services and message exchanges used for sharing cyber threat intelligence information between parties. Check `TAXII homepage <http://taxii.mitre.org/>`_ to get more information.
+
+
+Cabby is designed from the ground up to act as a Python library and as a command line tool, it's key features are:
 
 * **Rich feature set**:
   it supports all TAXII services according to TAXII specification (v1.0 and v1.1).
 
 * **Version agnostic**:
   it abstracts specific implementation details and returns version agnostic entities.
 
-* **Well designed from ground up**:
-  it is designed from ground up to act as a Python library and as a command line tool.
-
 
 .. rubric:: Documentation contents
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    installation
    user

docs/installation.rst

@@ -4,20 +4,43 @@ Installation guide
 
 .. highlight:: sh
 
-This guide provides installation instructions for Cabby.
+Install Python
+==============
 
+OpenTAXII works with Python version 2.7, which you can download `here <http://www.python.org/download/>`_ or with your operating system’s package manager. 
 
-Build and install Cabby
+You can verify that Python is installed by typing ``python`` from your shell; you should see something like::
+
+	$ python
+	Python 2.7.6 (default, Sep  9 2014, 15:04:36) 
+	[GCC 4.2.1 Compatible Apple LLVM 6.0 (clang-600.0.39)] on darwin
+	Type "help", "copyright", "credits" or "license" for more information.
+	>>> 
+
+Install Cabby
 =======================
 
-You can automatically install the latest Cabby release from the `Python
+To sandbox the project and protect system-wide python it is recommended to install Cabby into a `virtual environment <https://virtualenv.pypa.io/en/latest/installation.html>`_ (*virtualenv*)::
+
+Create a virtual environment named venv::
+
+   $ virtualenv venv
+
+Where ``venv`` is a directory to place the new environment
+
+Activate this environment::
+
+   $ source vENV/bin/activate
+   (venv) $
+   
+You can now install the latest Cabby release from the `Python
 Package Index <http://pypi.python.org/>`_ (PyPI) using ``pip``::
 
-   (envname) $ pip install cabby
+   (venv) $ pip install cabby
 
 .. note::
     Since Cabby has `libtaxii <https://github.com/TAXIIProject/libtaxii>`_ as a dependency, the system libraries
-    `libtaxii` requires needs to be installed. Check
+    `libtaxii` requires need to be installed. Check
     `libtaxii documentation <http://libtaxii.readthedocs.org/en/latest/installation.html#dependencies>`_ for the details.
 
 To install Cabby from source files: download a tarball, unpack it and install it manually with ``python setup.py install``.

docs/user.rst

@@ -2,20 +2,22 @@
 User guide
 ==========
 
-This user guide gives an overview of cabby. It covers:
+This user guide gives an overview of Cabby. It covers using Cabby as a:
 
-* using cabby as a Python library
-* using cabby as a command line tool
+* Python library
+* command line tool
 
 Note: this document assumes basic familiarity with TAXII specifications. Visit the `TAXII
 homepage`_ for more information about its features.
 
 .. _`TAXII homepage`: http://taxii.mitre.org/
 
 
-Using cabby as a Python library
+Using Cabby as a Python library
 ===============================
 
+Below a few examples of how to use the Cabby in your code.
+
 Create a client::
 
   from cabby import create_client
@@ -52,39 +54,39 @@ To force client to use `TAXII 1.0 <taxii.mitre.org/specifications/version1.0/TAX
 
   client = create_client('hailataxii.com', version='1.0')
 
-Note: TAXII 1.0 client will have a slightly different method signatures (see :doc:`Cabby API documentation<api>` for details)
-
+.. note::
+	Cabby client instances configured for TAXII 1.0 or TAXII 1.1 we will have slightly different method signatures (see :doc:`Cabby API documentation<api>` for details).
 
-Using cabby as a command line tool
+Using Cabby as a command line tool
 ==================================
 
-During installation cabby adds a family of the command line tools prefixed with ``taxii-`` to your path:
+During installation Cabby adds a family of the command line tools prefixed with ``taxii-`` to your path:
 
 .. highlight:: shell
 
 Discover services::
 
-  $ taxii-discovery --host taxiitest.mitre.org --path /services/discovery/
+  (venv) $ taxii-discovery --host taxiitest.mitre.org --path /services/discovery/
 
 Poll content from a collection (Polling Service autodiscovered in advertised services)::
 
-  $ taxii-poll --host taxiitest.mitre.org --collection default --discovery /services/discovery/
+  (venv) $ taxii-poll --host taxiitest.mitre.org --collection default --discovery /services/discovery/
 
 Fetch collections list from Collection Management Service::
 
-  $ taxii-collections --path https://taxii.example.com/services/collection-management
+  (venv) $ taxii-collections --path https://taxii.example.com/services/collection-management
 
 Push content into Inbox Service::
 
-  $ taxii-push --host taxiitest.mitre.org \
+  (venv) $ taxii-push --host taxiitest.mitre.org \
                --discovery /services/discovery \
                --content-file /tmp/stuxnet.stix.xml \
                --binding "urn:stix.mitre.org:xml:1.1.1" \
                --subtype custom-subtype
 
 Create a subscription::
 
-  $ taxii-subscription --host taxii.example.com \
+  (venv) $ taxii-subscription --host taxii.example.com \
                        --https \
                        --path /services/collection-management \
                        --action subscribe \