Merge 1576426 into ceca8fa

DEVELOP.rst

@@ -5,12 +5,15 @@ Developer Guide
 Setup
 =====
 
-This project uses buildout_ to set up the development environment.
+This project uses `buildout`_ to set up the development environment.
 
 To start things off, run::
 
     $ python bootstrap.py
 
+Your system python should be Python 3. If it isn't, try running `python3`
+instead. If that doesn't exist, you will have to install Python 3.
+
 Then, run::
 
     $ ./bin/buildout -N
@@ -22,7 +25,7 @@ Then to run your local crash, use::
 Running Tests
 =============
 
-The tests are run using the zope.testrunner_::
+The tests are run using the `zope.testrunner`_::
 
     $ ./bin/test
 
@@ -33,8 +36,8 @@ You can run the tests against multiple Python interpreters with tox_::
 
     $ ./bin/tox
 
-To do this, you will need ``python2.7``, ``python3.3``, and ``pypy`` on your
-``$PATH``.
+To do this, you will need (for example) ``python3.3`` (any other interpreters
+you want to test against) as well as ``pypy`` on your ``$PATH``.
 
 To run against a single interpreter, you can also do::
 
@@ -66,9 +69,9 @@ To create a new release, you must:
 
 - Create a tag by running ``./devtools/create_tag.sh``
 
-- Deploy to PyPI (see section below)
+- Deploy to PyPI (see below)
 
-- Archive docs for old releases (see section below)
+- Archive docs for old releases (see below)
 
 PyPI Deployment
 ---------------
@@ -77,11 +80,12 @@ To create the package use::
 
     $ bin/py setup.py sdist bdist_wheel
 
-Then, use twine_ to upload the package to PyPI_::
+Then, use twine_ to upload the package to `PyPI`_::
 
     $ bin/twine upload dist/*
 
-For this to work, you will need a personal PyPI account that is set up as a project admin.
+For this to work, you will need a personal PyPI account that is set up as a
+project admin.
 
 You'll also need to create a ``~/.pypirc`` file, like so::
 
@@ -94,7 +98,8 @@ You'll also need to create a ``~/.pypirc`` file, like so::
     username=<USERNAME>
     password=<PASSWORD>
 
-Here, ``<USERNAME>`` and ``<PASSWORD>`` should be replaced with your username and password, respectively.
+Here, ``<USERNAME>`` and ``<PASSWORD>`` should be replaced with your username
+and password, respectively.
 
 If you want to check the PyPI description before uploading, run::
 
@@ -105,7 +110,7 @@ Archiving Docs Versions
 
 Check the `versions hosted on ReadTheDocs`_.
 
-We should only be hosting the docs for `latest`, the last three minor release
+We should only be hosting the docs for ``latest``, the last three minor release
 branches of the last major release, and the last minor release branch
 corresponding to the last two major releases.
 
@@ -117,7 +122,7 @@ For example:
 - ``0.20``
 
 Because this project has not yet had a major release, as of yet, there are no
-major releases before `0` to include in this list.
+major releases before ``0`` to include in this list.
 
 Sometimes you might find that there are multiple older releases that need to be
 archived.
@@ -128,14 +133,15 @@ checkbox, and then saving.
 Standalone Deployment
 =====================
 
-The standalone executable is built and deployed by a Jenkins_ job.
+The standalone executable is built and deployed by a `Jenkins`_ job.
 
 Writing Documentation
 =====================
 
 The docs live under the ``docs`` directory.
 
-The docs are written written with ReStructuredText_ and processed with Sphinx_.
+The docs are written written with `ReStructuredText`_ and processed with
+`Sphinx`_.
 
 Build the docs by running::
 
@@ -154,5 +160,5 @@ nothing special you need to do to get the live docs to update.
 .. _Sphinx: http://sphinx-doc.org/
 .. _tox: http://testrun.org/tox/latest/
 .. _twine: https://pypi.python.org/pypi/twine
-.. _zope.testrunner: https://pypi.python.org/pypi/zope.testrunner/4.4.1
 .. _versions hosted on ReadTheDocs: https://readthedocs.org/projects/crash/versions/
+.. _zope.testrunner: https://pypi.python.org/pypi/zope.testrunner/4.4.1

README.rst

@@ -1,50 +1,60 @@
-=====
-Crash
-=====
+=================
+The CrateDB Shell
+=================
 
 .. image:: https://travis-ci.org/crate/crash.svg?branch=master
     :target: https://travis-ci.org/crate/crash
     :alt: Travis CI
 
-.. image:: https://badge.fury.io/py/crash.png
+.. image:: https://badge.fury.io/py/crash.svg
     :target: http://badge.fury.io/py/crash
     :alt: Version
 
 .. image:: https://img.shields.io/badge/docs-latest-brightgreen.svg
     :target: https://crate.io/docs/reference/crash/
     :alt: Documentation
 
-.. image:: https://img.shields.io/pypi/pyversions/crash.svg
-    :target: https://pypi.python.org/pypi/crash/
-    :alt: Python Version
-
-.. image:: https://img.shields.io/coveralls/crate/crash.svg
-    :target: https://coveralls.io/r/crate/crash?branch=master
+.. image:: https://coveralls.io/repos/github/crate/crash/badge.svg?branch=master
+    :target: https://coveralls.io/github/crate/crash?branch=master
     :alt: Coverage
 
 |
 
-Crash is an interactive CrateDB *command line interface* (CLI) SQL shell with autocompletion.
+
+The CrashDB Shell (aka *Crash*) is an interactive `command-line interface`_
+(CLI) tool for interacting with CrateDB.
 
 Screenshot
 ==========
 
-.. image:: crash.png
+.. image:: docs/query.png
     :alt: A screenshot of Crash
 
 Prerequisites
 =============
 
-Recent versions of Crash require **Python 3** (>= 3.4) to run.
+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.23.x`` if you are running Python 2.7/3.3 or version
-``0.16.x`` if you're running Python 2.6.
+Use Crash version 0.16.x if you're running Python 2.6.
 
 Installation
 ============
 
-As a Python Package
--------------------
+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.
 
@@ -60,39 +70,40 @@ To update, run::
 
     $ pip install -U crash
 
-If you use Python 2.7 or 3.3 with a recent version of pip_, it will install
-only version ``0.23.x`` by default, because newer versions of this package are
-not compatible with Python 2.7/3.3 any more.
+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.
 
 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.
+necessary dependencies, and can be run as long as Python (>= 3.4) is available
+on your system.
 
-First, download the executable::
+First, download the executable file::
 
     $ curl -o crash https://cdn.crate.io/downloads/releases/crash_standalone_latest
 
-Then, make it executable::
+Then, set the executable bit::
 
     $ chmod +x crash
 
 Now, run it::
 
     $ ./crash
 
-If you would like to run ``crash`` from any directory and without using leading
-``./`` you will need to move it to somewhere on your ``$PATH``.
+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::
+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::
+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
 
@@ -121,10 +132,12 @@ Looking for more help?
 - Chat with us on `Slack`_
 - Get `paid support`_
 
+.. _command-line interface: https://en.wikipedia.org/wiki/Command-line_interface
 .. _contribution docs: CONTRIBUTING.rst
 .. _Crate.io: http://crate.io/
 .. _developer docs: DEVELOP.rst
 .. _paid support: https://crate.io/pricing/
+.. _PATH: https://en.wikipedia.org/wiki/PATH_(variable)
 .. _pip: https://pypi.python.org/pypi/pip
 .. _Slack: https://crate.io/docs/support/slackin/
 .. _StackOverflow: https://stackoverflow.com/tags/crate

buildout.cfg

@@ -23,6 +23,7 @@ eggs = crash
 recipe = hexagonit.recipe.download
 url = https://cdn.crate.io/downloads/releases/crate-${versions:crate_server}.tar.gz
 strip-top-level-dir = true
+ignore-existing = true
 
 [test]
 relative-paths=true