Adding upstream version 2.8.1.upstream/2.8.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 146 insertions, 0 deletions

diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
new file mode 100644
index 0000000..412fb6a
--- /dev/null
+++ b/docs/source/configuration.rst
@@ -0,0 +1,146 @@
+*******************************
+Configuration and customization
+*******************************
+
+.. note::
+   **Forking the main GitHub repo is not needed to personalize Powerline 
+   configuration!** Please read through the :ref:`quick-guide` for a quick 
+   introduction to user configuration.
+
+Powerline is configured with one main configuration file, and with separate 
+configuration files for themes and colorschemes. All configuration files are 
+written in JSON, with the exception of segment definitions, which are 
+written in Python.
+
+Powerline provides default configurations in the following locations:
+
+:ref:`Main configuration <config-main>`
+    :file:`{powerline}/config.json`
+:ref:`Colorschemes <config-colorschemes>`
+    :file:`{powerline}/colorschemes/{name}.json`, 
+    :file:`{powerline}/colorschemes/{extension}/__main__.json`, 
+    :file:`{powerline}/colorschemes/{extension}/{name}.json`
+:ref:`Themes <config-themes>`
+    :file:`{powerline}/themes/{top_theme}.json`, 
+    :file:`{powerline}/themes/{extension}/__main__.json`, 
+    :file:`{powerline}/themes/{extension}/default.json`
+
+Here `{powerline}` is one of the following:
+
+#. The default configuration directory located in the main package: 
+   :file:`{powerline_root}/powerline/config_files`. May be absent in some 
+   packages (e.g. when installing via Gentoo ebuilds).
+#. If variable ``$XDG_CONFIG_DIRS`` is set and non-empty then to any 
+   :file:`{directory}/powerline` where `{directory}` is a directory listed in 
+   a colon-separated ``$XDG_CONFIG_DIRS`` list. Directories are checked in 
+   reverse order.
+#. User configuration directory located in :file:`$XDG_CONFIG_HOME/powerline`. 
+   This usually corresponds to :file:`~/.config/powerline` on all platforms.
+
+If per-instance configuration is needed please refer to :ref:`Local 
+configuration overrides <local-configuration-overrides>`.
+
+.. _configuration-merging:
+
+.. note::
+   Existing multiple configuration files that have the same name, but are placed 
+   in different directories, will be merged. Merging happens in the order given 
+   in the above list of possible `{powerline}` meanings.
+
+   When merging configuration only dictionaries are merged and they are merged 
+   recursively: keys from next file overrule those from the previous unless 
+   corresponding values are both dictionaries in which case these dictionaries 
+   are merged and key is assigned the result of the merge.
+
+.. note:: Some configuration files (i.e. themes and colorschemes) have two level
+    of merging: first happens merging described above, second theme- or 
+    colorscheme-specific merging happens.
+
+.. _quick-guide:
+
+Quick setup guide
+=================
+
+This guide will help you with the initial configuration of Powerline.
+
+Look at configuration in :file:`{powerline_root}/powerline/config_files`. If you 
+want to modify some file you can create :file:`~/.config/powerline` directory 
+and put modifications there: all configuration files are :ref:`merged 
+<configuration-merging>` with each other.
+
+Each extension (vim, tmux, etc.) has its own theme, and they are located in 
+:file:`{config directory}/themes/{extension}/default.json`. Best way to modify 
+it is to copy this theme as a whole, remove ``segment_data`` key with 
+corresponding value if present (unless you need to modify it, in which case only 
+modifications must be left) and do necessary modifications in the list of 
+segments (lists are not subject to merging: this is why you need a copy).
+
+If you want to move, remove or customize any of the provided segments in the 
+copy, you can do that by updating the segment dictionary in the theme you want 
+to customize. A segment dictionary looks like this:
+
+.. code-block:: javascript
+
+   {
+       "name": "segment_name"
+       ...
+   }
+
+You can move the segment dictionaries around to change the segment 
+positions, or remove the entire dictionary to remove the segment from the 
+prompt or statusline.
+
+.. note:: It’s essential that the contents of all your configuration files 
+   is valid JSON! It’s strongly recommended that you run your configuration 
+   files through ``jsonlint`` after changing them.
+
+.. note::
+   If your modifications appear not to work, run :ref:`powerline-lint script 
+   <command-powerline-lint>`. This script should show you the location of the 
+   error.
+
+Some segments need a user configuration to work properly. Here’s a couple of 
+segments that you may want to customize right away:
+
+**E-mail alert segment**
+    You have to set your username and password (and possibly server/port) 
+    for the e-mail alert segment. If you’re using GMail it’s recommended 
+    that you `generate an application-specific password 
+    <https://accounts.google.com/IssuedAuthSubTokens>`_ for this purpose.
+
+    Open a theme file, scroll down to the ``email_imap_alert`` segment and 
+    set your ``username`` and ``password``.  The server defaults to GMail’s 
+    IMAP server, but you can set the server/port by adding a ``server`` and 
+    a ``port`` argument.
+**Weather segment**
+    The weather segment will try to find your location using a GeoIP lookup, 
+    so unless you’re on a VPN you probably won’t have to change the location 
+    query.
+
+    If you want to change the location query or the temperature unit you’ll 
+    have to update the segment arguments. Open a theme file, scroll down to 
+    the weather segment and update it to include unit/location query 
+    arguments:
+
+    .. code-block:: javascript
+
+       {
+           "name": "weather",
+           "priority": 50,
+           "args": {
+               "unit": "F",
+               "location_query": "oslo, norway"
+           }
+       },
+
+References
+==========
+
+.. toctree::
+   :glob:
+
+   configuration/reference
+   configuration/segments
+   configuration/listers
+   configuration/selectors
+   configuration/local