Merge pull request #193 from dib-lab/fix/docs

Small fixes to documentation

docs/index.rst

@@ -3,13 +3,13 @@
     <img src="_static/kevlar-logo.png"alt="kevlar logo" style="height: 150px; display: block" />
 
 The **kevlar** library is a testbed for developing reference-free variant discovery methods for genomics.
-The initial focus of the project has been novel germline variant discovery in simplex pedigrees, but we are laying the groundwork to support more generalized case/control studies of large cohorts.
+The initial focus of the project has been discovery of *de novo* germline variants in simplex pedigrees, but we are laying the groundwork to support a wider range of experimental designs such as case/control studies.
 
-kevlar does not use a reference genome to identify variant associated reads or to assemble these reads into contigs representing each variant.
-However, the reference genome is still used for making the final variant call by aligning each assembled contig to a small cutout of the reference genome.
-The reference genome can also be used at various preliminary stages for filtering and improving kevlar's performance.
+We are advertising kevlar as a "reference-free" method in that it does not require a referene genome to identify variant associated reads or to assemble these reads into contigs representing each novel variant.
+However, the reference genome is currently still used for making the final variant call by aligning each assembled contig to a small cutout of the reference genome.
+One of the goals of the project moving forward is to reduce and eventually eliminate dependence on a reference genome completely.
 
-kevlar is currently under heavy development, and some features are not yet stable.
+kevlar is currently under heavy development, and internal features are not yet stable.
 However, the core features and workflows are reasonably well tested, and leverage software components from various third-party libraries that are very well tested and widely used.
 
 Documentation for **kevlar**

docs/install.rst

@@ -4,30 +4,38 @@ Installing **kevlar**
 For the impatient
 -----------------
 
-If this isn't your first time in the wing, the following 4 commands should be sufficient to install kevlar in the majority of cases.
+If this isn't your first time in the wing, the following commands should be sufficient to install kevlar in the majority of cases.
 Otherwise, we suggest reading through the entire installation instructions before beginning.
 
 .. code::
 
-    virtualenv kevlar-env
-    source kevlar-env/bin/activate  # Execute this with every new terminal session
-    pip install cython pysam networkx pandas git+https://github.com/dib-lab/khmer.git
+    pip install pysam networkx pandas scipy git+https://github.com/dib-lab/khmer.git
     pip install biokevlar
 
 Virtual environment
 -------------------
 
-We recommend installing kevlar and its dependencies in a dedicated `virtual environment <http://docs.python-guide.org/en/latest/dev/virtualenvs/>`_.
-The command :code:`virtualenv kevlar-env` will create a new virtual environment, and only needs to be executed once.
-The command :code:`source kevlar-env/bin/activate` will need to be re-executed any time you open a new session in your terminal.
+We recommend installing kevlar and its dependencies in a dedicated virtual environment using `venv <https://docs.python.org/3/library/venv.html>`_ or `conda <https://conda.io/docs/user-guide/tasks/manage-environments.html>`_.
+
+- If you use ``venv``, the command ``python3 -m venv kevlar-env`` will create a new virtual environment, and only needs to be executed once.
+  The command ``source kevlar-env/bin/activate`` will need to be re-executed any time you open a new session in your terminal.
+- If you use ``conda``, the command ``conda create --name kevlar-env python=3.6`` will create a new virtual environment, and only needs to be executed once.
+  The command ``source activate kevlar-env`` will need to be re-executed any time you open a new session in your terminal.
 
 .. note:: The label ``kevlar-env`` can be replaced with an alternative label if desired.
 
 Dependencies
 ------------
 
-The kevlar software has four non-standard dependencies: the `networkx <https://networkx.github.io/>`_ package, the `pysam <http://pysam.readthedocs.io/>`_ package, the `pandas <http://pandas.pydata.org/>`_ package, and the `khmer package <http://khmer.readthedocs.io/>`_.
-The kevlar installation procedure *should* handle the first three dependencies automatically, but since it relies on an unreleased version of **khmer** this last dependency must be installed manually.
+The kevlar software has several non-standard dependencies.
+
+- the `networkx package <https://networkx.github.io/>`_
+- the `pysam module <http://pysam.readthedocs.io/>`_
+- the `pandas library <http://pandas.pydata.org/>`_
+- the `scipy library <https://www.scipy.org/>`_
+- the `khmer package <http://khmer.readthedocs.io/>`_
+
+When kevlar is installed from PyPI most dependencies *should* handled automatically, but since kevlar relies on an unreleased version of **khmer** this last dependency must be installed manually.
 
 .. code::
 
@@ -39,7 +47,7 @@ The kevlar installation procedure *should* handle the first three dependencies a
 
    .. code::
 
-      pip install pysam>=0.11.2 networkx>=2.0 pandas git+https://github.com/dib-lab/khmer.git
+      pip install pysam>=0.11.2 networkx>=2.0 pandas scipy git+https://github.com/dib-lab/khmer.git
 
 Installation
 ------------
@@ -62,7 +70,7 @@ If you want to test whether kevlar is installed and running correctly, use pytes
 .. code::
 
     pip install pytest
-    pytest --pyargs kevlar
+    pytest --pyargs kevlar.tests
 
 Development environment
 -----------------------

docs/quick-start.rst

@@ -14,7 +14,7 @@ A :doc:`more detailed tutorial is available <tutorial>`, and a complete listing
         curl -L https://osf.io/fuaty/download?version=1 -o father.fq.gz
         curl -L https://osf.io/f5trh/download?version=1 -o proband.fq.gz
         curl -L https://osf.io/58rwa/download?version=1 -o refr.fa.gz
-        bwa index refr.fq.gz
+        bwa index refr.fa.gz
 
         kevlar simplex \
             --case proband.fq.gz --case-min 6 \