Noissue - Update R documentation

README.rst

 python-abp
 ==========
 
 This repository contains a library for working with Adblock Plus filter lists,
 a script for rendering diffs between filter lists, and the script that is used
 for building Adblock Plus filter lists from the form in which they are authored
 into the format suitable for consumption by the adblocking software (aka
 rendering).
 
 .. contents::
@@ skipping 192 matching lines @@
 from coverage tests by adding a comment, e.g. ``# pragma: no py2 cover``.
 
 All public functions, classes and methods should have docstrings compliant with
 `NumPy/SciPy documentation guide <https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_.
 One exception is the constructors of classes that the user is not expected to
 instantiate (such as exceptions).
 
 
 Using the library with R
 ------------------------
-
-``python-abp`` can be installed directly onto your system, or in a virtual
-environment. To install it directly onto your system with pip::
-
-    $ pip install --upgrade python-abp
-
-Or install onto your system from source::

[Vasily Kuznetsov, 2019/03/06 17:18:19]

Perhaps we could make this a bit more comprehensive and also remove repetition
if we use the following structure:

- How to install from PyPI
- How to install from local source
- How to use a virtualenv:
  - Show both py2 and py3 way of creating a virtualenv, link to
https://virtualenv.pypa.io/en/latest/userguide/#usage and
https://docs.python.org/3/library/venv.html
  - Explain that we can use /path/to/venv/bin/pip to install packages into the
virtualenv.
- Show how to import stuff in R with and without a virtualenv, link to
https://rstudio.github.io/reticulate/articles/versions.html

[rhowell, 2019/03/07 03:59:07]

Seems like it's starting to get complicated trying to cover every installation
use case, but hopefully this is an improvement. Oh, and is this what you meant
by 'both py2 and py3 ways of creating a virtualenv'?

-
-    $ cd python-abp
-    $ pip install --upgrade .

[Vasily Kuznetsov, 2019/03/06 17:18:19]

A simpler version would be:

    $ pip install -U /path/to/python-abp

Changing into the directory is not really necessary.

[rhowell, 2019/03/07 03:59:07]

Done.

-
-To install ``python-abp`` in a virtual environment with pip::
-
-    $ virtualenv venv
-    $ venv/bin/pip install --upgrade python-abp
-
-Or install from source in a virtualenv::
-
-    $ cd python-abp
-    $ virtualenv venv
-    $ venv/bin/pip install --upgrade .
-
-Then import it with ``reticulate`` in R:
+Installation
+~~~~~~~~~~~~
+``python-abp`` can be installed from PyPI or from the source code, either
+directly onto a system or in a virtual environment.
+
+To install from PyPI::
+
+    $ pip install -U python-abp
+
+To install from a local source, clone the repo and then::
+
+    $ pip install -U /path/to/python-abp
+
+To use the virtual environment, it must first be created. Python 2 and 3 use
+different scripts to create a virtualenv.
+
+In Python 2::
+
+    $ virtualenv env
+
+In Python 3::
+
+    $ python3 -m venv env
+
+Then, use the virtualenv's version of pip to install python-abp, either from
+PyPI or from source (as shown above)::
+
+    $ env/bin/pip install -U python-abp
+
+For more information about virtualenv, please see the `User Guide`_ and the
+docs_.
+
+Usage
+~~~~~
+In R, ``python-abp`` can be imported with ``reticulate``:
 
 .. code-block:: R
 
     > library(reticulate)
-    > use_virtualenv("~/path/to/python-abp/venv", required=TRUE)  # If using virtualenv
+    > use_virtualenv("~/path/to/env", required=TRUE)  # If using virtualenv
     > abp <- import("abp.filters.rpy")
 
 Now you can use the functions with ``abp$functionname``, e.g.
-``abp$line2dict("@@||g.doubleclick.net/pagead/$subdocument,domain=hon30.org")``.
+``abp$line2dict("@@||g.doubleclick.net/pagead/$subdocument,domain=hon30.org")``
+
+For more information about the reticulate package, see their guide_.
+
+.. _User Guide: https://virtualenv.pypa.io/en/latest/userguide/#usage
+.. _docs: https://docs.python.org/3/library/venv.html
+.. _guide: https://rstudio.github.io/reticulate/