Update README and install sample configs

Change-Id: Iac32f7a02f29622b618940a5a5ba4254f650f09f

CONTRIBUTING.rst

@@ -1,3 +1,6 @@
+Contributing
+============
+
 To browse the latest code, see: https://git.openstack.org/cgit/stackforge/gertty/tree/
 To clone the latest code, use `git clone git://git.openstack.org/stackforge/gertty`
 
@@ -11,3 +14,47 @@ that links to your launchpad account). Example::
     # Do your commits
     $ git review
     # Enter your username if prompted
+
+Philosophy
+----------
+
+Gertty is based on the following precepts which should inform changes
+to the program:
+
+* Support large numbers of review requests across large numbers of
+  projects.  Help the user prioritize those reviews.
+
+* Adopt a news/mailreader-like workflow in support of the above.
+  Being able to subscribe to projects, mark reviews as "read" without
+  reviewing, etc, are all useful concepts to support a heavy review
+  load (they have worked extremely well in supporting people who
+  read/write a lot of mail/news).
+
+* Support off-line use.  Gertty should be completely usable off-line
+  with reliable syncing between local data and Gerrit when a
+  connection is available (just like git or mail or news).
+
+* Ample use of color.  Unlike a web interface, a good text interface
+  relies mostly on color and precise placement rather than whitespace
+  and decoration to indicate to the user the purpose of a given piece
+  of information.  Gertty should degrade well to 16 colors, but more
+  (88 or 256) may be used.
+
+* Keyboard navigation (with easy-to-remember commands) should be
+  considered the primary mode of interaction.  Mouse interaction
+  should also be supported.
+
+* The navigation philosophy is a stack of screens, where each
+  selection pushes a new screen onto the stack, and ESC pops the
+  screen off.  This makes sense when drilling down to a change from
+  lists, but also supports linking from change to change (via commit
+  messages or comments) and navigating back intuitive (it matches
+  expectations set by the web browsers).
+
+* Support a wide variety of Gerrit installations.  The initial
+  development of Gertty is against the OpenStack project's Gerrit, and
+  many of the features are intended to help its developers with their
+  workflow, however, those features should be implemented in a generic
+  way so that the system does not require a specific Gerrit
+  configuration.
+

README.rst

@@ -22,90 +22,104 @@ As compared to the web interface, the main advantages are:
    repos, a single command instructs it to checkout a change into that
    repo for detailed examination or testing of larger changes.
 
+Installation
+------------
+
+It is recommended (but not required) to install Gertty in a
+virtualenv.  To do set one up::
+
+  virtualenv gertty-env
+  source gertty-env/bin/activate
+
+To install the latest version from the cheeseshop::
+
+  pip install gertty
+
+To install from a git checkout::
+
+  pip install .
+
+Gertty uses a YAML based configuration file that it looks for at
+``~/.gertty.yaml``.  Several sample configuration files are included.
+You can find them in the examples/ directory of the source
+distribution or the share/gertty/examples directory after installation.
+
+Select one of the sample config files, copy it to ~/.gertty.yaml and
+edit as necessary.  Search for ``CHANGEME`` to find parameters that
+need to be supplied.  The sample config files are as follows:
+
+**minimal-gertty.yaml**
+  Only contains the parameters required for Gertty to actually run.
+
+**reference-gertty.yaml**
+  An exhaustive list of all supported options with examples.
+
+**openstack-gertty.yaml**
+  A configuration designed for use with OpenStack's installation of
+  Gerrit.
+
+You will need your Gerrit password which you can generate or retrieve
+by navigating to ``Settings``, then ``HTTP Password``.
+
+Gertty uses local git repositories to perform much of its work.  These
+can be the same git repositories that you use when developing a
+project.  Gertty will not alter the working directory or index unless
+you request it to (and even then, the usual git safeguards against
+accidentally losing work remain in place).  You will need to supply
+the name of a directory where Gertty will find or clone git
+repositories for your projects as the ``git-root`` parameter.
+
+The config file is designed to support multiple Gerrit instances.  The
+first one is used by default, but others can be specified by supplying
+the name on the command line.
+
 Usage
 -----
 
-Create a file at ``~/.gertty.yaml`` with the following contents::
+After installing Gertty, you should be able to run it by invoking
+``gertty``.  If you installed it in a virtualenv, you can invoke it
+without activating the virtualenv with ``/path/to/venv/bin/gertty``
+which you may wish to add to your shell aliases.  Use ``gertty
+--help`` to see a list of command line options available.
 
-  servers:
+Once Gertty is running, you will need to start by subscribing to some
-    - name: gerrit
+projects.  Use 'L' to list all of the projects and then 's' to
-      url: https://review.example.org/
+subscribe to the ones you are interested in.  Hit 'L' again to shrink
-      username: <gerrit username>
+the list to your subscribed projects.
-      password: <gerrit password>
-      git_root: ~/git/
-
-A sample file with several options configured for use with OpenStack's
-Gerrit is available in ``gertty.yaml-sample``.
-
-You can generate or retrieve your Gerrit password by navigating to
-Settings, then HTTP Password.  Set ``git_root`` to a directory where
-Gertty should find or clone git repositories for your projects.
-
-If your Gerrit uses a self-signed certificate, you can add::
-
-  verify_ssl: False
-
-To the section.
-
-The config file is designed to support multiple Gerrit instances, but
-currently, only the first one is used.
-
-After installing the requirements (listed in requirements.txt), you
-should be able to simply run Gertty.  You will need to start by
-subscribing to some projects.  Use 'l' to list all of the projects and
-then 's' to subscribe to them.
 
 In general, pressing the F1 key will show help text on any screen, and
 ESC will take you to the previous screen.
 
+Gertty works seamlessly offline or online.  All of the actions that it
+performs are first recorded in a local database (in ``~/.gertty.db``
+by default), and are then transmitted to Gerrit.  If Gertty is unable
+to contact Gerrit for any reason, it will continue to operate against
+the local database, and once it re-establishes contact, it will
+process any pending changes.
+
+The status bar at the top of the screen displays the current number of
+outstanding tasks that Gertty must perform in order to be fully up to
+date.  Some of these tasks are more complicated than others, and some
+of them will end up creating new tasks (for instance, one task may be
+to search for new changes in a project which will then produce 5 new
+tasks if there are 5 new changes).  This will explain why the number
+of tasks displayed in the status bar sometimes changes rapidly.
+
+If Gertty is offline, it will so indicate in the status bar.  It will
+retry requests if needed, and will switch between offline and online
+mode automatically.
+
+If Gertty encounters an error, this will also be indicated in the
+status bar.  You may wish to examine ~/.gertty.log to see what the
+error was.  In may cases, Gertty can continue after encountering an
+error.  The error flag will be cleared when you leave the current
+screen.
+
 To select text (e.g., to copy to the clipboard), hold Shift while
 selecting the text.
 
-Philosophy
-----------
-
-Gertty is based on the following precepts which should inform changes
-to the program:
-
-* Support large numbers of review requests across large numbers of
-  projects.  Help the user prioritize those reviews.
-
-* Adopt a news/mailreader-like workflow in support of the above.
-  Being able to subscribe to projects, mark reviews as "read" without
-  reviewing, etc, are all useful concepts to support a heavy review
-  load (they have worked extremely well in supporting people who
-  read/write a lot of mail/news).
-
-* Support off-line use.  Gertty should be completely usable off-line
-  with reliable syncing between local data and Gerrit when a
-  connection is available (just like git or mail or news).
-
-* Ample use of color.  Unlike a web interface, a good text interface
-  relies mostly on color and precise placement rather than whitespace
-  and decoration to indicate to the user the purpose of a given piece
-  of information.  Gertty should degrade well to 16 colors, but more
-  (88 or 256) may be used.
-
-* Keyboard navigation (with easy-to-remember commands) should be
-  considered the primary mode of interaction.  Mouse interaction
-  should also be supported.
-
-* The navigation philosophy is a stack of screens, where each
-  selection pushes a new screen onto the stack, and ESC pops the
-  screen off.  This makes sense when drilling down to a change from
-  lists, but also supports linking from change to change (via commit
-  messages or comments) and navigating back intuitive (it matches
-  expectations set by the web browsers).
-
-* Support a wide variety of Gerrit installations.  The initial
-  development of Gertty is against the OpenStack project's Gerrit, and
-  many of the features are intended to help its developers with their
-  workflow, however, those features should be implemented in a generic
-  way so that the system does not require a specific Gerrit
-  configuration.
-
 Contributing
 ------------
 
-For information on how to contribute to gertty, please see the
+For information on how to contribute to Gertty, please see the
 contents of the CONTRIBUTING.rst file.

examples/minimal-gertty.yaml

@@ -0,0 +1,9 @@
+# This is an example ~/.gertty.yaml file with only the required
+# settings.
+
+servers:
+  - name: CHANGEME
+    url: https://CHANGEME.example.org/
+    username: CHANGEME
+    password: CHANGEME
+    git-root: ~/git/

examples/openstack-gertty.yaml

@@ -8,27 +8,46 @@ servers:
     url: https://review.openstack.org/
     username: CHANGEME
     password: CHANGEME
-    git_root: ~/git/
+    git-root: ~/git/
 
+# This section adds the colors that we will reference later in the
+# commentlinks section for test results.  You can also change other
+# colors here.
 palettes:
   - name: default
-    test-SUCCESS: ['light green', '', '']
+    test-SUCCESS: ['light green', '']
-    test-FAILURE: ['light red', '', '']
+    test-FAILURE: ['light red', '']
 
 # Uncomment the next line if your terminal has a white background
 # palette: light
 
+# Commentlinks are regexes that are applied to commit and review
+# messages.  They can be replaced with internal or external links, or
+# have colors applied.
 commentlinks:
+  # This matches the job results left by Zuul.
   - match: "^- (?P<job>.*?) (?P<url>.*?) : (?P<result>[^ ]+) ?(?P<comment>.*)$"
+    # This indicates that this is a test result, and should be indexed
+    # using the "job" match group from the commentlink regex.  Gertty
+    # displays test results in their own area of the screen.
     test-result: "{job}"
     replacements:
+      # Replace the matching text with a hyperlink to the "url" match
+      # group whose text is the "job" match group.
       - link:
           text: "{job:<42}"
           url: "{url}"
+      # Follow that with the plain text of the "result" match group
+      # with the color "test-{result}" applied.  See the palette
+      # section above.
       - text:
           color: "test-{result}"
           text: "{result} "
+      # And then follow that with the plain text of the "comment"
+      # match group.
       - text: "{comment}"
+  # Match Gerrit change ids, and replace them with a link to an
+  # internal Gertty search for that change id.
   - match: "(?P<id>I[0-9a-fA-F]{40})"
     replacements:
       - search:
@@ -38,7 +57,6 @@ commentlinks:
 # This is the query used for the list of changes when a project is
 # selected.  The default is "status:open"; if you don't want to see
 # WIP changes, use a query like this: 
-#
 # change-list-query: "status:open not label:Workflow=-1"
 
 # Uncomment the following line to use a unified diff view instead
@@ -50,11 +68,22 @@ commentlinks:
 hide-comments:
   - author: "^(.*CI|Jenkins)$"
 
+# This section defines customized dashboards.  You can supply any
+# Gertty search string and bind them to any key.  They will appear in
+# the global help text, and pressing the key anywhere in Gertty will
+# discard the current display stack and replace it with the results of
+# the query.
 dashboards:
   - name: "My changes"
     query: "owner:self status:open"
     key: "f2"
 
+# Reviewkeys are hotkeys that perform immediate reviews within the
+# change screen.  Any pending comments or review messages will be
+# attached to the review; otherwise an empty review will be left.  The
+# approvals list is exhaustive, so if you specify an empty list,
+# Gertty will submit a review that clears any previous approvals.
+# They will appear in the help text for the change screen.
 reviewkeys:
   - key: 'meta 0'
     approvals: []

examples/reference-gertty.yaml

@@ -0,0 +1,166 @@
+# This is an example ~/.gertty.yaml with an exhaustive listing of
+# options with commentary.
+
+# This section lists the servers that Gertty can talk to.  Multiple
+# servers may be listed; by default, Gertty will use the first one
+# listed.  To select another, simply specify its name on the command
+# line.
+servers:
+  - name: CHANGEME
+    url: https://CHANGEME.example.org/
+    username: CHANGEME
+    password: CHANGEME
+    git_root: ~/git/
+
+# Each server section can have the following fields:
+# A name that describes the server, to reference on the command line. [required]
+#  - name: sample
+# The URL of the Gerrit server.  HTTPS should be preferred. [required]
+#    url: https://example.org/
+# Your username in Gerrit. [required]
+#    username: CHANGEME
+# Your password in Gerrit (Settings -> HTTP Password). [required]
+#    password: CHANGEME
+# A location where Gertty should store its git repositories.  These
+# can be the same git repositories where you do your own work --
+# Gertty will not modify them unless you tell it to, and even then the
+# normal git protections against losing work remain in place. [required]
+#    git-root: ~/git/
+# The location of Gertty's sqlite database.  If you have more than one
+# server, you should specify a dburi for any additional servers.
+#    dburi: ~/.gertty.db
+# If your Gerrit server has a self-signed cert (eg, a test server),
+# you can set this value to false to turn of certificate validation.
+#    verify-ssl: true
+# By default Gertty logs errors to a file and truncates that file each
+# time it starts (so that it does not grow without bound).  If you
+# would like to log to a different location, you may specify it here.
+#    log-file: ~/.gertty.log
+
+# Gertty comes with two palettes defined internally.  The default
+# palette is suitable for use on a terminal with a dark background.
+# The "light" palette is for a terminal with a white or light
+# background.  You may customize the colors in either of those
+# palettes, or define your own palette.
+
+# The following alters two colors in the default palette, one color in
+# the light palette, and one color in a custom palette.  If any color
+# is not defined in a palette, the value from the default palette is
+# used.  The values are a list of at least two elements describing the
+# colors to be use for the foreground and background colors.
+# Additional elements can specify (in order) the color to use for
+# monochrome terminals, the foreground, and background colors to use
+# in high-color terminals.
+
+# For a reference of possible color names, see:
+# http://urwid.org/manual/displayattributes.html#foreground-and-background-settings
+# To see the list of possible palette entries, run "gertty --print-palette".
+
+palettes:
+  - name: default
+    added-line: ['dark green', '']
+    added-word: ['light green', '']
+  - name: light
+    filename: ['dark cyan', '']
+  - name: custom
+    filename: ['light yellow', '']
+
+# Palettes may be selected at runtime with the "-p PALETTE" command
+# line option, or you may set the default palette here:
+# palette: light
+
+# Keymaps work the same way as palettes.  Only one keymap is defined
+# internally, the default keymap.  Individual keys may be overridden
+# and custom keymaps defined and selected in the config file or the
+# command line.
+
+# Each keymap contains a mapping of command -> key(s).  If a command
+# is not specified, Gertty will use the keybinding specified in the
+# default map.  More than one key can be bound to a command.
+
+# Run "gertty --print-keymap" for a list of commands that can be
+# bound.
+
+keymaps:
+  - name: default
+    diff: 'd'
+  - name: custom
+    review: ['r', 'R']
+
+# The default keymap may be selected with the '-k KEYMAP' command line
+# option, or with the following line:
+# keymap: custom
+
+# Commentlinks are regular expressions that are applied to commit and
+# review messages.  They can be replaced with internal or external
+# links, or have colors applied.
+commentlinks:
+# Match Gerrit change ids, and replace them with a link to an internal
+# Gertty search for that change id.
+  - match: "(?P<id>I[0-9a-fA-F]{40})"
+    replacements:
+      - search:
+          text: "{id}"
+          query: "change:{id}"
+# Any number of commentlink entries may be specified.  Start each with
+# a "match" key and regex.  Named match groups within the regex may be
+# used in the replacements section.  Any number of replacements may be
+# specified.  The types of replacement available are:
+#
+# Text: Plain text whose color may be specified.  The color references
+# a palette entry.
+#      - text:
+#          color: ""
+#          text: ""
+# Link: A hyperlink with the indicated text that when activated will
+# open the user's browser with the supplied URL
+#      - link:
+#          text: ""
+#          url: ""
+# Search: A hyperlink that will perform a Gertty search when
+# activated.
+#      - search:
+#          text: "{id}"
+#          query: "change:{id}"
+
+# This is the query used for the list of changes when a project is
+# selected.  The default is "status:open".
+# change-list-query: "status:open"
+
+# Uncomment the following line to use a unified diff view instead
+# of the default side-by-side:
+# diff-view: unified
+
+# Uncomment the following lines to Hide comments by default that match
+# certain criteria.  You can toggle their display with 't'.  Currently
+# the only supported criterion is "author".
+# hide-comments:
+#  - author: "^(.*CI|Jenkins)$"
+
+# This section defines customized dashboards.  You can supply any
+# Gertty search string and bind them to any key.  They will appear in
+# the global help text, and pressing the key anywhere in Gertty will
+# discard the current display stack and replace it with the results of
+# the query.
+dashboards:
+  - name: "My changes"
+    query: "owner:self status:open"
+    key: "f2"
+
+# Reviewkeys are hotkeys that perform immediate reviews within the
+# change screen.  Any pending comments or review messages will be
+# attached to the review; otherwise an empty review will be left.  The
+# approvals list is exhaustive, so if you specify an empty list,
+# Gertty will submit a review that clears any previous approvals.
+# They will appear in the help text for the change screen.
+reviewkeys:
+  - key: 'meta 0'
+    approvals: []
+  - key: 'meta 1'
+    approvals:
+      - category: 'Code-Review'
+        value: 1
+  - key: 'meta 2'
+    approvals:
+      - category: 'Code-Review'
+        value: 2

gertty/config.py

@@ -193,19 +193,11 @@ class Config(object):
         return None
 
     def printSample(self):
-        print """Please create a configuration file ~/.gertty.yaml
+        filename = 'share/gertty/examples'
+        print """Gertty requires a configuration file at ~/.gertty.yaml
 
-Example:
+Several sample configuration files were installed with Gertty and are
+available in %s in the root of the installation.
 
------8<-------8<-----8<-----8<---
+For more information, please see the README.
-servers:
+""" % (filename,)
-  - name: gerrit
-    url: https://review.example.org/
-    username: <gerrit username>
-    password: <gerrit password>
-    git_root: ~/git/
------8<-------8<-----8<-----8<---
-
-Then invoke:
-  gertty gerrit
-        """

setup.cfg

@@ -22,6 +22,8 @@ keywords = gerrit console urwid review
 [files]
 packages =
     gertty
+data_files =
+    share/gertty/examples = examples/*
 
 [entry_points]
 console_scripts =