Merge 042fba3 into 4ad81a9

README.rst

@@ -27,36 +27,16 @@ The CrashDB Shell (aka *Crash*) is an interactive `command-line interface`_
 Screenshot
 ==========
 
-.. image:: docs/query.png
+.. image:: https://raw.githubusercontent.com/crate/crash/master/docs/query.png
     :alt: A screenshot of Crash
 
-Prerequisites
-=============
-
-Recent versions of Crash require Python 3 (>= 3.4) to run.
-
-Use Crash version 0.23.x if you are running Python 2.7 or 3.3.
-
-Use Crash version 0.16.x if you're running Python 2.6.
-
 Installation
 ============
 
-Under normal circumstances, you do not have to manually install Crash.
-
-Crash is bundled with CrateDB so there is typically no need to install it
-yourself.
-
-If you are able to run the ``crate`` command, you should be able to run the
-``crash`` command (either from the same ``bin`` directory, or on your `PATH`_).
-
-The following instructions should only be followed if you specifically want to
-install Crash separately from CrateDB.
-
 Python Package
 --------------
 
-Crash is available as a pip_ package.
+Crash is available as a `pip`_ package.
 
 To install, run::
 
@@ -68,9 +48,9 @@ Now, run it::
 
 To update, run::
 
-    $ pip install -U crash
+     $ pip install -U crash
 
-If you are not using Python version 3.4 or above, recent version of pip_ will
+If you are not using Python version 3.4 or above, recent version of `pip`_ will
 only install version 0.23.x. This is because newer versions of this package are
 not compatible with Python 2.7 or 3.3 and below.
 
@@ -96,24 +76,6 @@ Now, run it::
 If you would like to run ``crash`` from any directory, and without the leading
 ``./``, the file has to be in a directory that is on your `PATH`_.
 
-Legacy Versions
-...............
-
-For Python 2.7 and 3.3 please download version 0.23.0 from the CDN::
-
-    $ curl -o crash https://cdn.crate.io/downloads/releases/crash_standalone_0.23.0
-
-For Python 2.6 please download version 0.16.2 from the CDN::
-
-    $ curl -o crash https://cdn.crate.io/downloads/releases/crash_standalone_0.16.2
-
-Usage
-=====
-
-For usage information and options, run::
-
-    $ crash --help
-
 Contributing
 ============
 

docs/appendices/compatibility.txt

@@ -14,12 +14,36 @@ Compatibility
 Version Notes
 =============
 
+.. _python-versions
+
+Python
+------
+
+You must be running the following versions of Python:
+
++----------------+-----------------+
+| Client Version | Python Version  |
++================+=================+
+| >= 0.23        | >=3.4           |
++----------------+-----------------+
+| 0.23.x         | 3.3             |
++----------------+-----------------+
+| 0.23.x         | 2.7             |
++----------------+-----------------+
+| 0.16.x         | 2.6             |
++----------------+-----------------+
+
+.. NOTE::
+
+    If you are using `pip`_, the highest compatible version of the client will
+    be installed according to the version of Python you are using.
+
 .. _cratedb-versions:
 
 CrateDB
 -------
 
-Consult the following table for CrateDB version compatibility notes:
+Consult the following table for CrateDB compatibility notes:
 
 +----------------+-----------------+-------------------------------------------+
 | Client Version | CrateDB Version | Notes                                     |
@@ -52,6 +76,7 @@ Consult the following table for CrateDB version compatibility notes:
 .. _array constructors: https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#array-constructor
 .. _client library: https://crate.io/docs/crate/getting-started/en/latest/start-building/index.html
 .. _CrateDB REST endpoint: https://crate.io/docs/crate/reference/en/latest/interfaces/http.html
-.. _object literals: https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#object-literals
 .. _create your own users: https://crate.io/docs/crate/reference/en/latest/admin/user-management.html
 .. _enterprise edition: https://crate.io/products/cratedb-enterprise/
+.. _object literals: https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#object-literals
+.. _pip: https://pypi.python.org/pypi/pip

docs/getting-started.txt

@@ -9,39 +9,99 @@ Getting Started
 .. contents::
    :local:
 
-Install
-=======
-
-Crash is bundled with `CrateDB`_ so there is typically no need to install it
-yourself.
+Installation
+============
 
 .. SEEALSO::
 
-   For manual installation instructions, consult the `PyPI overview`_.
+    Consult the :ref:`compatibility` appendix for prerequisites information.
+
+Python Package
+--------------
+
+Crash is available as a `pip`_ package.
+
+To install, run:
+
+.. code-block:: console
+
+    sh$ pip install crash
+
+Now, run it:
+
+.. code-block:: console
+
+    sh$ crash
+
+To update, run:
+
+.. code-block:: console
+
+    sh$ pip install -U crash
+
+Standalone
+----------
+
+Crash is also available as a standalone executable that includes all the
+necessary dependencies, and can be run as long as Python (>= 3.4) is available
+on your system.
+
+First, download the executable file:
+
+.. code-block:: console
+
+    sh$ curl -o crash https://cdn.crate.io/downloads/releases/crash_standalone_latest
+
+Then, set the executable bit:
+
+.. code-block:: console
+
+    sh$ chmod +x crash
+
+Now, run it:
+
+.. code-block:: console
+
+    sh$ ./crash
+
+If you would like to run ``crash`` from any directory, and without the leading
+``./``, the file has to be in a directory that is on your `PATH`_.
+
+Legacy Versions
+...............
+
+For Python 2.7 and 3.3 please download version 0.23.0 from the CDN:
+
+.. code-block:: console
+
+    sh$ curl -o crash https://cdn.crate.io/downloads/releases/crash_standalone_0.23.0
+
+For Python 2.6 please download version 0.16.2 from the CDN:
+
+.. code-block:: console
+
+    sh$ curl -o crash https://cdn.crate.io/downloads/releases/crash_standalone_0.16.2
 
 Run
 ===
 
-If you are able to run the ``crate`` command (see `Running CrateDB`_), you
-should be able to run the ``crash`` command. Both of these executable files
-live inside the main CrateDB ``bin`` directory.
+You can start Crash like so:
 
-If the CrateDB ``bin`` directory is on your `PATH`_, you can start Crash like
-so::
+.. code-block:: console
 
   sh$ crash
 
-Otherwise, locate the CrateDB directory, and run it like so::
-
-  sh$ ./bin/crash
-
 When ``crash`` is run without any additional arguments, it will attempt to
 connect to ``localhost:4200``. To connect to another host, use the ``--hosts``
-flag. For example::
+flag. For example:
+
+.. code-block:: console
+
+  sh$ crash --host "198.51.100.1"
 
-  sh$ crash --host 198.51.100.1
+If you are experiencing a connection error, try the ``--verbose`` flag:
 
-If you are experiencing a connection error, try the ``--verbose`` flag::
+.. code-block:: console
 
   sh$ crash --verbose
 
@@ -85,6 +145,7 @@ You should see something like this:
 .. _CrateDB REST Endpoint: https://crate.io/docs/current/sql/rest.html
 .. _CrateDB: https://crate.io/products/cratedb/
 .. _PATH: https://en.wikipedia.org/wiki/PATH_(variable)
+.. _pip: https://pypi.python.org/pypi/pip
 .. _PyPI overview: https://pypi.python.org/pypi/crash/
 .. _Running CrateDB: https://crate.io/docs/crate/reference/en/latest/run.html
 .. _shell: https://en.wikipedia.org/wiki/Shell_(computing)

docs/run.txt

@@ -107,7 +107,9 @@ The ``crash`` executable supports multiple command-line options:
 Examples
 --------
 
-Here's an example command::
+Here's an example command:
+
+.. code-block:: console
 
     sh$ crash --hosts node1.example.com \
                     node2.example.com \
@@ -132,14 +134,16 @@ This command will:
    Instead of `redirecting`_ to a file, you can `pipe`_ into a tool like `jq`_
    for for further processing of the response.
 
-We can modify this command to use SSL, like so::
+We can modify this command to use SSL, like so:
+
+.. code-block:: console
 
     sh$ crash --hosts node1.example.com \
                     node2.example.com \
             --verify-ssl true \
             --cert-file ~/.certs/client.crt \
             --key-file ~/.certs/client.key \
-            --ca-cert-file ~/.certs/server-ca.crt
+            --ca-cert-file ~/.certs/server-ca.crt \
             -c "SELECT * FROM sys.nodes" \
             --format json \
         > output.json
@@ -186,7 +190,9 @@ At the moment, only one environment variable is supported.
                  Storing passwords in the environment is not always a good idea
                  from a security perspective.
 
-You can set ``CRATEPW`` like so::
+You can set ``CRATEPW`` like so:
+
+.. code-block:: console
 
     sh$ export CRATEPW=<PASSWORD>