Improve Documentation (#835)

* Update installation documentation to include virtualenv example

* Add notice about ampersand replacement in pango markup

* Remove rubric header

* Forgot to add the installation.rst

* Fix typo

README.rst

@@ -17,35 +17,37 @@ i3pystatus is a large collection of status modules compatible with i3bar from th
 Installation
 ------------
 
-**Supported Python versions**
-    i3pystatus requires Python 3.6 or newer and is not compatible with
-    Python 2.x. Some modules require additional dependencies
-    documented in the docs.
+i3pystatus requires Python 3.6 or newer and is not compatible with Python 2.
+Some modules require additional dependencies documented in the docs.
 
-::
-
-    pip3 install git+https://github.com/enkore/i3pystatus.git
+Detailed installation instructions can be found `here
+<https://i3pystatus.readthedocs.io/en/latest/installation.html>`_.
 
 Documentation
 -------------
 
-`All further user documentation has been moved here. <https://i3pystatus.readthedocs.io/>`_
+The official documentation is located at https://i3pystatus.readthedocs.io.
 
-The changelog for old releases can be found `here. <https://i3pystatus.readthedocs.io/en/latest/changelog.html>`_
+The changelog for old releases can be found `here <https://i3pystatus.readthedocs.io/en/latest/changelog.html>`_.
 
 Contributors
 ------------
 
-A list of all contributors can be found in `CONTRIBUTORS <https://github.com/enkore/i3pystatus/blob/master/CONTRIBUTORS>`_, but git likely has more up-to-date information. i3pystatus was initially written by Jan Oliver Oelerich and later ported to Python 3 and mostly rewritten by enkore.
+A list of all contributors can be found in `CONTRIBUTORS
+<https://github.com/enkore/i3pystatus/blob/master/CONTRIBUTORS>`_, but git
+likely has more up-to-date information. i3pystatus was initially written by Jan
+Oliver Oelerich and later ported to Python 3 and mostly rewritten by enkore.
 
 Contribute
 ----------
 
-To contribute a module, make sure it uses one of the ``Module`` classes. Most modules
-use ``IntervalModule``, which just calls a function repeatedly in a specified interval.
+To contribute a module, make sure it uses one of the ``Module`` classes. Most
+modules use ``IntervalModule``, which just calls a function repeatedly in a
+specified interval.
 
-The ``output`` attribute should be set to a dictionary which represents your modules output,
-the protocol is documented `here <http://i3wm.org/docs/i3bar-protocol.html>`_.
+The ``output`` attribute should be set to a dictionary which represents your
+module's output, the protocol is documented `here
+<http://i3wm.org/docs/i3bar-protocol.html>`_.
 
 Developer documentation is available in the source code and `here
 <https://i3pystatus.readthedocs.io/en/latest/module.html>`_.

docs/configuration.rst

@@ -1,9 +1,10 @@
 Configuration
 =============
 
-The configuration file is a normal Python script. The status bar is controlled by a central
-:py:class:`.Status` object, which individual *modules* like a :py:mod:`.clock` or a :py:mod:`.battery`
-monitor are added to with the ``register`` method.
+The configuration file is a normal Python script. The status bar is controlled
+by a central :py:class:`.Status` object, which individual *modules* like a
+:py:mod:`.clock` or a :py:mod:`.battery` monitor are added to with the
+``register`` method.
 
 A typical configuration file could look like this (note the additional
 dependencies from :py:mod:`.network` and :py:mod:`.pulseaudio` in this
@@ -468,7 +469,10 @@ Some possible uses for these attributes are:
     provides additional formatting options for drawing rainbows and other
     fancy stuff.
 
-.. note:: Pango markup requires that i3bar is configured to use `Pango <http://i3wm.org/docs/userguide.html#fonts>`_, too. It can't work with X core fonts.
+.. note::
+   Pango markup requires that i3bar is configured to use `Pango
+   <http://i3wm.org/docs/userguide.html#fonts>`_, too. It can't work with X
+   core fonts.
 
 Here is an example with the :py:mod:`.network` module.
 Pango markup is used to keep the ESSID green at all times while the
@@ -513,6 +517,12 @@ Or make two modules look like one.
             text = "Antidisestabli",
             color="#FF0000")
 
+.. note::
+    To prevent pango rendering errors, ampersands in the formatted text will be
+    replaced with the HTML escape code ``&amp;``. Any ampersands that are
+    themselves part of an HTML escape (e.g. ``&lt;``, ``&gt;``, etc.) will not
+    be replaced.
+
 .. _refresh:
 
 Refreshing the bar

docs/index.rst

@@ -7,6 +7,7 @@ Contents:
 .. toctree::
    :maxdepth: 4
 
+   installation
    configuration
    i3pystatus
    changelog

docs/installation.rst

@@ -0,0 +1,57 @@
+Installation
+============
+
+.. rubric:: Supported Python Versions
+
+i3pystatus requires Python 3.6 or newer and is not compatible with Python 2.
+Some modules require additional dependencies documented in the docs.
+
+Into Virtualenv
+---------------
+
+i3pystatus no longer uses numbered releases. Therefore, the recommended method
+is to install from git via ``pip``, and into a virtualenv to avoid polluting
+your site-packages directory.
+
+First, create a virtualenv:
+
+.. code-block:: bash
+
+    $ python3 -mvenv /path/to/virtualenv
+
+Next, activate into the virtualenv and use pip to install i3pystatus into it:
+
+.. code-block:: bash
+
+    $ source /path/to/virtualenv/bin/activate
+    $ pip install git+https://github.com/enkore/i3pystatus.git
+
+If you are installing for development, use ``pip install --editable`` instead:
+
+.. code-block:: bash
+
+    $ source /path/to/virtualenv/bin/activate
+    $ pip install --editable /path/to/clone/of/i3pystatus
+
+**NOTE:** If you need to install any additional dependencies required by the
+i3pystatus modules you are using, you will also need to install them into this
+virtualenv.
+
+Invoking From Virtualenv
+------------------------
+
+To invoke i3pystatus from your virtualenv, use the ``python`` symlink from the
+virtualenv to run your i3pystatus config script. See the following example
+``bar`` section from ``~/.config/i3/config``:
+
+.. code-block:: text
+
+    bar {
+        colors {
+             statusline #949494
+             separator #4e4e4e
+        }
+        separator_symbol "|"
+        position top
+        status_command /path/to/virtualenv/bin/python /home/username/.config/i3/status.py
+    }