Start on documentation with installation instruction

Author: rhpvorderman

README.rst

@@ -72,57 +72,12 @@ application (just like ``python -m gzip``).
 
 Installation
 ------------
-Installation with pip
-.....................
+- with pip: ``pip install isal``
+- with conda: ``conda install python-isal``
 
-::
-
-    pip install isal
-
-Installation is supported on Linux, MacOS and Windows. On x86-64 (amd64)
-platforms wheels are provided, so installation should be almost instantaneous.
-The installation will include a staticallly linked version of ISA-L.
-If a wheel is not provided for your system the
-installation will build ISA-L first in a temporary directory. Please check the
-`ISA-L homepage <https://github.com/intel/isa-l>`_ for the build requirements.
-
-The latest development version of python-isal can be installed with::
-
-    pip install git+https://github.com/rhpvorderman/python-isal.git
-
-This requires having the build requirements installed.
-If you wish to link
-dynamically against a version of libisal installed on your system use::
-
-     PYTHON_ISAL_LINK_DYNAMIC=true pip install isal --no-binary isal
-
-ISA-L is available in numerous Linux distro's as well as on conda via the
-conda-forge channel. Checkout the `ports documentation
-<https://github.com/intel/isa-l/wiki/Ports--Repos>`_ on the ISA-L project wiki
-to find out how to install it. It is important that the development headers
-are also installed.
-
-On Debian and Ubuntu the ISA-L libraries (including the development headers)
-can be installed with::
-
-  sudo apt install libisal-dev
-
-Installation via conda
-..................................
-Python-isal can be installed via conda, for example using
-the `miniconda <https://docs.conda.io/en/latest/miniconda.html>`_ installer
-with a properly setup `conda-forge 
-<https://conda-forge.org/docs/user/introduction.html#how-can-i-install-packages-from-conda-forge>`_
-channel. When used with bioinformatics tools setting up `bioconda 
-<http://bioconda.github.io/user/install.html#install-conda>`_
-provides a clear set of installation instructions for conda.
-
-python-isal is available on conda-forge and can be installed with::
-
-  conda install python-isal
-
-This will automatically install the ISA-L library dependency as well, since
-it is available on conda-forge.
+Installation is supported on Linux, Windows and MacOS. For more advanced
+installation options check the `documentation
+<https://python-isal.readthedocs.io>`_.
 
 Differences with zlib and gzip modules
 --------------------------------------

docs/conf.py

@@ -40,15 +40,19 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+# includes/* prevents double indexing
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'includes/*']
 
 
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
+html_theme_options = dict(
+    display_version=True,
+)
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

docs/includes/Installation.rst

@@ -0,0 +1,53 @@
+Installation
+------------
+Installation with pip
+.....................
+
+::
+
+    pip install isal
+
+Installation is supported on Linux, MacOS and Windows. On most platforms
+wheels are provided.
+The installation will include a staticallly linked version of ISA-L.
+If a wheel is not provided for your system the
+installation will build ISA-L first in a temporary directory. Please check the
+`ISA-L homepage <https://github.com/intel/isa-l>`_ for the build requirements.
+
+The latest development version of python-isal can be installed with::
+
+    pip install git+https://github.com/rhpvorderman/python-isal.git
+
+This requires having the build requirements installed.
+If you wish to link
+dynamically against a version of libisal installed on your system use::
+
+     PYTHON_ISAL_LINK_DYNAMIC=true pip install isal --no-binary isal
+
+ISA-L is available in numerous Linux distro's as well as on conda via the
+conda-forge channel. Checkout the `ports documentation
+<https://github.com/intel/isa-l/wiki/Ports--Repos>`_ on the ISA-L project wiki
+to find out how to install it. It is important that the development headers
+are also installed.
+
+On Debian and Ubuntu the ISA-L libraries (including the development headers)
+can be installed with::
+
+  sudo apt install libisal-dev
+
+Installation via conda
+..................................
+Python-isal can be installed via conda, for example using
+the `miniconda <https://docs.conda.io/en/latest/miniconda.html>`_ installer
+with a properly setup `conda-forge
+<https://conda-forge.org/docs/user/introduction.html#how-can-i-install-packages-from-conda-forge>`_
+channel. When used with bioinformatics tools setting up `bioconda
+<http://bioconda.github.io/user/install.html#install-conda>`_
+provides a clear set of installation instructions for conda.
+
+python-isal is available on conda-forge and can be installed with::
+
+  conda install python-isal
+
+This will automatically install the ISA-L library dependency as well, since
+it is available on conda-forge.

docs/igzip.rst renamed to docs/includes/igzip.rst

@@ -10,14 +10,8 @@ Welcome to python-isal's documentation!
    :maxdepth: 2
    :caption: Contents:
 
-   isal_zlib
-   igzip
+.. include:: includes/Installation.rst
 
+.. include:: includes/isal_zlib.rst
 
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. include:: includes/igzip.rst

docs/isal_zlib.rst renamed to docs/includes/isal_zlib.rst

@@ -1,2 +1,3 @@
 sphinx
 setuptools
+sphinx-rtd-theme