Add configuration information to docs

This is basically the reference config file translated to rst.

This also makes some minor updates to the reference config file.

Change-Id: I6aa3f9a7410a219ad00cee827ac4c273cf54bff5

doc/source/configuration.rst

@@ -39,3 +39,378 @@ 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.
+
+Configuration Reference
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The following describes the values that may be set in the
+configuration file.
+
+Servers
++++++++
+
+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**
+  A list of server definitions.  The format of each entry is described
+  below.
+
+  **name (required)**
+    A name that describes the server, to reference on the command
+    line.
+
+  **url (required)**
+    The URL of the Gerrit server.  HTTPS should be preferred.
+
+  **username (required)**
+    Your username in Gerrit. [required]
+
+  **password (required)**
+    Your password in Gerrit.  Obtain it from Settings -> HTTP Password
+    in the Gerrit web interface.
+
+  **auth-type**
+    Authentication type required by the Gerrit server. Can be 'basic'
+    or 'digest'. Defaults to 'digest' if not set or set to an
+    unexpected value.
+
+  **git-root (required)**
+    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.
+
+  **dburi**
+    The location of Gertty's sqlite database.  If you have more than
+    one server, you should specify a dburi for any additional servers.
+    By default a SQLite database called ~/.gertty.db is used.
+
+  **ssl-ca-path**
+    If your Gerrit server uses a non-standard certificate chain
+    (e.g. on a test server), you can pass a full path to a bundle of
+    CA certificates here:
+
+  **verify-ssl**
+    In case you do not care about security and want to use a
+    sledgehammer approach to SSL, you can set this value to false to
+    turn off certificate validation.
+
+  **log-file**
+    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
+    with this option.
+
+  **socket**
+    Gertty listens on a unix domain socket for remote commands at
+    ~/.gertty.sock.  This option may be used to change the path.
+
+Example:
+
+.. code-block: yaml
+   servers:
+     - name: CHANGEME
+       url: https://CHANGEME.example.org/
+       username: CHANGEME
+       password: CHANGEME
+       git-root: ~/git/
+
+Palettes
+++++++++
+
+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.
+
+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 used for the foreground and background.
+Additional elements may 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 the `Urwid Manual
+<http://urwid.org/manual/displayattributes.html#foreground-and-background-settings>`_
+
+To see the list of possible palette entries, run `gertty --print-palette`.
+
+The following example alters two colors in the default palette, one
+color in the light palette, and one color in a custom palette.
+
+.. code-block: yaml
+   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 in the config file.
+
+**palette**
+  This option specifies the default palette.
+
+Keymaps
++++++++
+
+Keymaps work the same way as palettes.  Two keymaps are defined
+internally, the `default` keymap and the `vi` 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.
+
+The following example modifies the `default` keymap:
+
+.. code-block: yaml
+   keymaps:
+     - name: default
+       diff: 'd'
+     - name: custom
+       review: ['r', 'R']
+     - name: osx #OS X blocks ctrl+o
+       change-search: 'ctrl s'
+
+
+To specify a sequence of keys, they must be a list of keystrokes
+within a list of key series.  For example:
+
+.. code-block: yaml
+   keymaps:
+     - name: vi
+       quit: [[':', 'q']]
+
+The default keymap may be selected with the `-k KEYMAP` command line
+option, or in the config file.
+
+**keymap**
+  Set the default keymap.
+
+Commentlinks
+++++++++++++
+
+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**
+  This is a list of commentlink patterns.  Each commentlink pattern is
+  a dictionary with the following values:
+
+  **match**
+    A regular expression to match against the text of commit or review
+    messages.
+
+  **replacements**
+    A list of replacement actions to apply to any matches found.
+    Several replacement actions are supported, and each accepts
+    certain options.  These options may include strings extracted from
+    the regular expression match in named groups by enclosing the
+    group name in '{}' braces.
+
+  The following replacement actions are supported:
+
+    **text**
+      Plain text whose color may be specified.
+
+      **text**
+        The replacement text.
+
+      **color**
+        The color in which to display the text.  This references a
+        palette entry.
+
+    **link**
+      A hyperlink with the indicated text that when activated will
+      open the user's browser with the supplied URL
+
+      **text**
+        The replacement text.
+
+      **url**
+        The color in which to display the text.  This references a
+        palette entry.
+
+    **search**
+      A hyperlink that will perform a Gertty search when activated.
+
+      **text**
+        The replacement text.
+
+      **query**
+        The search query to use.
+
+This example matches Gerrit change ids, and replaces them with a link
+to an internal Gertty search for that change id.
+
+.. code-block: yaml
+   commentlinks:
+     - match: "(?P<id>I[0-9a-fA-F]{40})"
+       replacements:
+         - search:
+             text: "{id}"
+             query: "change:{id}"
+
+Change List Options
++++++++++++++++++++
+
+**change-list-query**
+  This is the query used for the list of changes when a project is
+  selected.  The default is `status:open`.
+
+**change-list-options**
+  This section defines default sorting options for the change list.
+
+  **sort-by**
+    This key specifies the sort order, which can be `number` (the
+    Change number), `updated` (when the change was last updated), or
+    `last-seen` (when the change was last opened in Gertty).
+
+  **reverse**
+    This is a boolean value which indicates whether the list should be
+    in ascending (`true`) or descending (`false`) order.
+
+Example:
+
+.. code-block: yaml
+   change-list-options:
+     sort-by: 'number'
+     reverse: false
+
+**thread-changes**
+  Dependent changes are displayed as "threads" in the change list by
+  default.  To disable this behavior, set this value to false.
+
+Change View Options
++++++++++++++++++++
+
+**hide-comments**
+  This is a list of descriptors which cause matching comments to be
+  hidden by default.  Press the `t` key to toggle the display of
+  matching comments.
+
+The only supported criterion is `author`.
+
+  **author**
+    A regular expression to match against the comment author's name.
+
+For example, to hide comments from a CI system:
+
+.. code-block: yaml
+
+   hide-comments:
+     - author: "^(.*CI|Jenkins)$"
+
+**diff-view**
+  Specifies how patch diffs should be displayed.  The values `unified`
+  or `side-by-side` (the default) are supported.
+
+
+Dashboards
+++++++++++
+
+This section defines customized dashboards.  You may 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
+run the query and display the results.
+
+**dashboards**
+  A list of dashboards, the format of which is described below.
+
+  **name**
+    The name of the dashboard.  This will be displayed in the status
+    bar at the top of the screen.
+
+  **query**
+    The search query to perform to gather changes to be listed in the
+    dashboard.
+
+  **key**
+    The key to which the dashboard should be bound.
+
+Example:
+
+.. code-block: yaml
+
+   dashboards:
+     - name: "My changes"
+       query: "owner:self status:open"
+       key: "f2"
+
+Reviewkeys
+++++++++++
+
+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 message 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.
+Reviewkeys appear in the help text for the change screen.
+
+**reviewkeys**
+  A list of reviewkey definitions, the format of which is described
+  below.
+
+  **key**
+    This key to which this review action should be bound.
+
+  **approvals**
+    A list of approvals to include when this reviewkey is activated.
+    Each element of the list should include both a category and a
+    value.
+
+    **category**
+      The name of the review label for this approval.
+
+    **value**
+      The value for this approval.
+
+  **submit**
+    Set this to `true` to instruct Gerrit to submit the change when
+    this reviewkey is activated.
+
+The following example includes a reviewkey that clears all labels, as
+well as one that leaves a +1 "Code-Review" approval.
+
+.. code-block: yaml
+
+   reviewkeys:
+     - key: 'meta 0'
+       approvals: []
+     - key: 'meta 1'
+       approvals:
+         - category: 'Code-Review'
+           value: 1
+
+General Options
++++++++++++++++
+
+**display-times-in-utc**
+  Times are displayed in the local timezone by default.  To display
+  them in UTC instead, set this value to `true`.
+
+**handle-mouse**
+  Gertty handles mouse input by default.  If you don't want it
+  interfering with your terminal's mouse handling, set this value to
+  `false`.
+
+**expire-age**
+  By default, closed changes that are older than two months are
+  removed from the local database (and their refs are removed from the
+  local git repos so that git may garbage collect them).  If you would
+  like to change the expiration delay or disable it, uncomment the
+  following line.  The time interval is specified in the same way as
+  the "age:" term in Gerrit's search syntax.  To disable it
+  altogether, set the value to the empty string.

examples/reference-gertty.yaml

@@ -87,10 +87,10 @@ palettes:
 # line option, or you may set the default palette here:
 # palette: light
 
-# Keymaps work the same way as palettes.  Only one keymap is defined
+# Keymaps work the same way as palettes.  Two keymaps are defined
-# internally, the default keymap.  Individual keys may be overridden
+# internally, the 'default' keymap and the 'vi' keymap.  Individual
-# and custom keymaps defined and selected in the config file or the
+# keys may be overridden and custom keymaps defined and selected in
-# command line.
+# 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
@@ -104,7 +104,7 @@ keymaps:
     diff: 'd'
   - name: custom
     review: ['r', 'R']
-  - name: osx #OS X blocks ctrl+o
+  - name: osx # OS X blocks ctrl+o
     change-search: 'ctrl s'
 # To specify a sequence of keys, they must be a list of keystrokes
 # within a list of key series.  For example:
@@ -193,8 +193,7 @@ commentlinks:
 # 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
+# run the query and display the results.
-# the query.
 #
 # NB: "recentlyseen:24 hours" does not just return changes seen in the
 # last 24 hours -- it returns changes seen within 24 hours of the most