Properly reference differences

Author: rhpvorderman

README.rst

@@ -48,23 +48,23 @@ a variety of functions to provide zlib/gzip-compatible compression.
 ``python-isal`` provides the bindings by offering three modules:
 
 + ``isal_zlib``: A drop-in replacement for the zlib module that uses ISA-L to
-                 accelerate its performance.
-+ ``igzip``:     A drop-in replacement for the gzip module that uses
-                 ``isal_zlib`` instead of ``zlib`` to perform its compression
-                 tasks, which improves performance.
+  accelerate its performance.
++ ``igzip``: A drop-in replacement for the gzip module that uses ``isal_zlib``
+  instead of ``zlib`` to perform its compression and checksum tasks, which
+  improves performance.
 + ``igzip_lib``: Provides compression functions which have full access to the
-                 API of ISA-L's compression functions.
+  API of ISA-L's compression functions.
 
 ``isal_zlib`` and ``igzip`` are almost fully compatible with ``zlib`` and
 ``gzip`` from the Python standard library. There are some minor differences
-which are listed below.
+see: :ref:`differences`.
 
 .. introduction end
 
 Quickstart
 ----------
 
-.. usage start
+.. quickstart start
 
 The python-isal modules can be imported as follows
 
@@ -86,7 +86,7 @@ application (just like ``python -m gzip``). Full usage documentation can be
 found on `our readthedocs page <https://python-isal.readthedocs.io>`_.
 
 
-.. usage end
+.. quickstart end
 
 Installation
 ------------
@@ -97,6 +97,8 @@ Installation is supported on Linux, Windows and MacOS. For more advanced
 installation options check the `documentation
 <https://python-isal.readthedocs.io/en/stable/index.html#installation>`_.
 
+.. _differences:
+
 Differences with zlib and gzip modules
 --------------------------------------
 

docs/index.rst

@@ -23,26 +23,9 @@ Introduction
 Quickstart
 ==========
 
-Python-isal has faster versions of the stdlib's ``zlib`` and ``gzip`` module
-these are called ``isal_zlib`` and ``igzip`` respectively.
-
-They can be imported as follows
-
-.. code-block:: python
-
-    from isal import isal_zlib
-    from isal import igzip
-
-``isal_zlib`` and ``igzip`` are meant to be used as drop in replacements so
-their api and functions are the same as the stdlib's modules. Except where
-ISA-L does not support the same calls as zlib (See differences below).
-
-A full API documentation can be found below.
-
-``python -m isal.igzip`` implements a simple gzip-like command line
-application (just like ``python -m gzip``). Full usage documentation can be
-found below.
-
+.. include:: includes/README.rst
+   :start-after: .. quickstart start
+   :end-before: .. quickstart end
 
 ============
 Installation
@@ -99,6 +82,8 @@ python-isal is available on conda-forge and can be installed with::
 This will automatically install the ISA-L library dependency as well, since
 it is available on conda-forge.
 
+.. _differences:
+
 ======================================
 Differences with zlib and gzip modules
 ======================================