diff --git a/README.rst b/README.rst index 1575648..b5e6f6f 100644 --- a/README.rst +++ b/README.rst @@ -3,7 +3,7 @@ i3pystatus .. image:: https://travis-ci.org/enkore/i3pystatus.svg?branch=master :target: https://travis-ci.org/enkore/i3pystatus - + .. image:: https://readthedocs.org/projects/i3pystatus/badge/?version=latest :target: https://i3pystatus.readthedocs.io/en/latest/?badge=latest @@ -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 +`_. Documentation ------------- -`All further user documentation has been moved here. `_ +The official documentation is located at https://i3pystatus.readthedocs.io. -The changelog for old releases can be found `here. `_ +The changelog for old releases can be found `here `_. Contributors ------------ -A list of all contributors can be found in `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 +`_, 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 `_. +The ``output`` attribute should be set to a dictionary which represents your +module's output, the protocol is documented `here +`_. Developer documentation is available in the source code and `here `_. diff --git a/docs/configuration.rst b/docs/configuration.rst index 6367424..71d7049 100644 --- a/docs/configuration.rst +++ b/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 `_, too. It can't work with X core fonts. +.. note:: + Pango markup requires that i3bar is configured to use `Pango + `_, 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 ``&``. Any ampersands that are + themselves part of an HTML escape (e.g. ``<``, ``>``, etc.) will not + be replaced. + .. _refresh: Refreshing the bar diff --git a/docs/index.rst b/docs/index.rst index 421b47e..f59453d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,6 +7,7 @@ Contents: .. toctree:: :maxdepth: 4 + installation configuration i3pystatus changelog diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..a8d492b --- /dev/null +++ b/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 + }