Merge pull request #72 from pycompression/more_docs

Add extensive documentation

Author: rhpvorderman

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,3 +1,4 @@
 
 ### Checklist
 - [ ] Pull request details were added to CHANGELOG.rst
+- [ ] Documentation was updated (if needed)

CHANGELOG.rst

@@ -7,6 +7,10 @@ Changelog
 .. This document is user facing. Please word the changes in such a way
 .. that users understand how the changes affect the new version.
 
+version 0.10.0-dev
+------------------
++ Added more extensive documentation.
+
 version 0.9.0
 -----------------
 + Fix a bug where a AttributeError was triggered when zlib.Z_RLE or

README.rst

@@ -34,6 +34,8 @@
 python-isal
 ===========
 
+.. introduction start
+
 Faster zlib and gzip compatible compression and decompression
 by providing Python bindings for the ISA-L library.
 
@@ -47,8 +49,12 @@ a variety of functions to provide zlib/gzip-compatible compression.
 ``igzip`` module which are usable as drop-in replacements for the ``zlib``
 and ``gzip`` modules from the stdlib (with some minor exceptions, see below).
 
-Usage
------
+.. introduction end
+
+Quickstart
+----------
+
+.. usage start
 
 Python-isal has faster versions of the stdlib's ``zlib`` and ``gzip`` module
 these are called ``isal_zlib`` and ``igzip`` respectively.
@@ -68,65 +74,26 @@ A full API documentation can be found on `our readthedocs page
 <https://python-isal.readthedocs.io>`_.
 
 ``python -m isal.igzip`` implements a simple gzip-like command line
-application (just like ``python -m gzip``).
-
-Installation
-------------
-Installation with pip
-.....................
-
-::
-
-    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
+application (just like ``python -m gzip``). Full usage documentation can be
+found on `our readthedocs page <https://python-isal.readthedocs.io>`_.
 
-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
+.. usage end
 
-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
+Installation
+------------
+- with pip: ``pip install isal``
+- with conda: ``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/en/stable/index.html#installation>`_.
 
 Differences with zlib and gzip modules
 --------------------------------------
 
+.. differences start
+
 + Compression level 0 in ``zlib`` and ``gzip`` means **no compression**, while
   in ``isal_zlib`` and ``igzip`` this is the **lowest compression level**.
   This is a design choice that was inherited from the ISA-L library.
@@ -151,8 +118,47 @@ Differences with zlib and gzip modules
   to reflect this. ``igzip.GzipFile`` does exist as an alias of
   ``igzip.IGzipFile`` for compatibility reasons.
 
+.. differences end
+
 Contributing
 ------------
+.. contributing start
+
 Please make a PR or issue if you feel anything can be improved. Bug reports
 are also very welcome. Please report them on the `github issue tracker
 <https://github.com/rhpvorderman/python-isal/issues>`_.
+
+.. contributing end
+
+Acknowledgements
+----------------
+
+.. acknowledgements start
+
+This project builds upon the software and experience of many.  Many thanks to:
+
++ The `ISA-L contributors
+  <https://github.com/intel/isa-l/graphs/contributors>`_ for making ISA-L.
++ The `Cython contributors
+  <https://github.com/cython/cython/graphs/contributors>`_ for making it easy
+  to create an extension and helping a novice get start with pointer addresses.
++ The `CPython contributors
+  <https://github.com/python/cpython/graphs/contributors>`_.
+  Python-isal mimicks ``zlibmodule.c`` and ``igzip.py`` to make it easier for
+  python users to adopt it.
++ `@marcelm <https://github.com/marcelm>`_ for taking a chance on this project
+  and make it a dependency for his `xopen
+  <https://github.com/pycompression/xopen>`_ and by extension `cutadapt
+  <https://github.com/marcelm/cutadapt>`_ projects. This gave python-isal its
+  first users who used python-isal in production.
++ The `github actions team <https://github.com/orgs/actions/people>`_ for
+  creating the actions CI service that enables building and testing on all
+  three major operating systems.
++ `@animalize <https://github.com/animalize>`_ for explaining how to test and
+  build python-isal for ARM 64-bit platforms.
++ And last but not least: everyone who submitted a bug report or a feature
+  request. These make the project better!
+
+Python-isal would not have been possible without you!
+
+.. acknowledgements end

docs/conf.py

@@ -31,24 +31,27 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.autodoc"
-]
+extensions = ["sphinx.ext.autodoc", 'sphinxarg.ext']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # 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/CHANGELOG.rst

@@ -0,0 +1 @@
+../../CHANGELOG.rst

docs/includes/Installation.rst

@@ -0,0 +1,54 @@
+============
+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/includes/README.rst

@@ -0,0 +1 @@
+../../README.rst

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

@@ -1,3 +1,4 @@
+========================
 API-documentation: igzip
 ========================
 

docs/includes/isal.igzip_usage.rst

@@ -0,0 +1,8 @@
+==========================
+python -m isal.igzip usage
+==========================
+
+.. argparse::
+   :module: isal.igzip
+   :func: _argument_parser
+   :prog: python -m isal.igzip

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

@@ -1,3 +1,4 @@
+============================
 API Documentation: isal_zlib
 ============================