add install and contribution guides, update readme

benvanwerkhoven · benvanwerkhoven · commit 0ca3c0683954 · 2017-04-06T15:56:15.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,10 +2,16 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
-## [Unreleased]
+## Unreleased
+
+
+## [0.1.3] - 2017-04-06
 ### Changed
 - changed how scalar arguments are handled internally
 
+### Added
+- separate install and contribution guides
+
 ## [0.1.2] - 2017-03-29
 ### Changed
 - allow non-tuple problem_size for 1D grids
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -0,0 +1,66 @@
+Contribution guide
+==================
+
+The kernel tuner follows the Google Python style guide, with Sphinxdoc 
+docstrings for module public functions. If you want to contribute to the project 
+please fork it, create a branch including your changes and additions, and create 
+a pull request.
+
+Before creating a pull request please ensure the following:
+
+* You have written unit tests to test your additions and all unit tests pass
+* The examples still work and produce the same (or better) results
+* The code is compatible with both Python 2.7 and Python 3.5
+* An entry about the change or addition is created in CHANGELOG.md
+* Any matching entries in the roadmap.md are updated/removed
+
+If you are in doubt on where add your additions to the Kernel Tuner, please 
+have look at the `design documentation <http://benvanwerkhoven.github.io/kernel_tuner/design.html>`__.
+
+Development setup
+-----------------
+
+You can install the packages required to run the tests using:
+
+.. code-block:: bash
+
+    pip install -r requirements-dev.txt
+
+After this command you should be able to run the tests and build the documentation.
+See below on how to do that.
+
+Running tests
+-------------
+
+To run the tests you can use ``pytest -v`` in the top-level directory. Note that 
+pytest tests against the installed package. To update the installed package 
+after you've made changes use:
+
+.. code-block:: bash
+
+    pip install --upgrade .
+    pytest -v
+
+Note that tests that require PyCuda and/or a CUDA capable GPU will be skipped if these
+are not installed/present. The same holds for thats that require PyOpenCL.
+
+Contributions you make to the Kernel Tuner should not break any of the tests 
+even if you can not run them locally.
+
+The examples can be seen as *integration tests* for the Kernel Tuner. Note that 
+these will also use the installed package.
+
+Building documentation
+----------------------
+
+Documentation is located in the ``doc/`` directory. This is where you can type 
+``make html`` to generate the html pages in the ``doc/build/html`` directory.
+
+The source files used for building the documentation is located in 
+``doc/source``. The tutorials should be included in the ``tutorials/`` directory 
+and a symlink can be used to add them to the source files for building 
+documentation.
+
+To update the documentation pages hosted on the GitHub the generated contents of 
+``doc/build/html`` should be copied to the top-level directory of the 
+``gh-pages`` branch.
diff --git a/INSTALL.rst b/INSTALL.rst
@@ -0,0 +1,121 @@
+Installation Guide
+==================
+
+The Kernel Tuner requires several packages to be installed. First of all you need a 
+working Python version, several Python packages, and optionally CUDA and/or OpenCL 
+installations. All of this is explained in detail in this guide.
+
+
+Python
+------
+
+First of all you need a Python installation. I recommend using Python 3 and 
+installing it with `Miniconda <https://conda.io/miniconda.html>`__.
+
+Linux users could type the following to download and install Python 3 using Miniconda:
+
+.. code-block:: bash
+
+    wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh
+    bash Miniconda3-latest-Linux-x86_64.sh
+
+You are of course also free to use your own Python installation, and the Kernel Tuner
+is developed to be fully compatible with Python 3.5 and newer, and also Python 2.7.
+
+Installing Python Packages
+--------------------------
+
+Note that when you are using a native Python installation, the `pip` commands used to 
+install dependencies probably require `sudo` rights. 
+
+Sudo rights are typically not required when using Miniconda or virtual environments.
+
+The following command will install all required dependencies:
+
+.. code-block:: bash
+
+    pip install -r requirements.txt
+
+There are also optional dependencies, explained below.
+
+CUDA and PyCUDA
+---------------
+
+Installing CUDA and PyCUDA is optional, because you may want to only use the Kernel 
+Tuner for tuning OpenCL or C kernels.
+
+If you want to use the Kernel Tuner to tune 
+CUDA kernels you will first need to install the CUDA toolkit 
+(https://developer.nvidia.com/cuda-toolkit).
+
+It's very important that you install the CUDA toolkit before trying to install PyCuda.
+
+You can install PyCuda using:
+
+.. code-block:: bash
+
+    pip install pycuda
+
+If you run into trouble with installing PyCuda, make sure you have CUDA installed first.
+Also make sure that the Python package Numpy is already installed (this should be the case
+because it is also a requirement for the Kernel Tuner).
+
+If you retry the ``pip install pycuda`` command you may need to use the 
+``--no-cache-dir`` option to ensure the pycuda installation really starts over.
+
+If this fails, I recommend to see the PyCuda 
+installation guide (https://wiki.tiker.net/PyCuda/Installation)
+
+
+OpenCL and PyOpenCL
+-------------------
+
+Before we can install PyOpenCL you'll need an OpenCL compiler. There are several 
+OpenCL compilers available depending on the OpenCL platform you want to your 
+code to run on.
+
+`AMD APP SDK <http://developer.amd.com/tools-and-sdks/opencl-zone/amd-accelerated-parallel-processing-app-sdk/>`__
+`Intel OpenCL <https://software.intel.com/en-us/iocl_rt_ref>`__
+`CUDA Toolkit <https://developer.nvidia.com/cuda-toolkit>`__
+`Apple OpenCL <https://developer.apple.com/opencl/>`__
+`Beignet <https://www.freedesktop.org/wiki/Software/Beignet/>`__
+
+You can also look at this `OpenCL Installation Guide <https://wiki.tiker.net/OpenCLHowTo>`__ for PyOpenCL.
+
+After you've installed your OpenCL compiler of choice you can install PyOpenCL using:
+
+.. code-block:: bash
+
+    pip install pyopencl
+
+If this fails, please see the PyOpenCL installation guide (https://wiki.tiker.net/PyOpenCL/Installation)
+
+
+Installing the Kernel Tuner
+---------------------------
+
+So far we've talked about all the dependencies, but not the Kernel Tuner itself.
+
+The easiest way to install is using pip:
+
+.. code-block:: bash
+
+    pip install kernel_tuner
+
+But you can also install from the git repository. This way you also get the 
+examples and the tutorials.
+
+.. code-block:: bash
+
+    git clone https://github.com/benvanwerkhoven/kernel_tuner.git
+    cd kernel_tuner
+    pip install -r requirements.txt
+    pip install .
+
+Then go to any of the ``examples/cuda`` or ``examples/opencl`` directories
+and see if you can run the ``vector_add.py`` example to test your installation.
+
+
+
+
+
diff --git a/README.rst b/README.rst
@@ -36,41 +36,34 @@ The full documentation is available
 Installation
 ------------
 
-To install from PyPi:  
+The easiest way to install the Kernel Tuner is using pip:
 
-- ``pip install kernel_tuner``  
+.. code-block:: bash
 
-To install from the source (and get the tutorial and examples):  
+    pip install kernel_tuner
 
-- clone the repository  
- 
-  - With a GitHub account: ``git clone git@github.com:benvanwerkhoven/kernel_tuner.git``  
-  - Without GitHub account: ``git clone https://github.com/benvanwerkhoven/kernel_tuner.git``  
-   
-- change into the top-level directory  
+But you can also install from the git repository. This way you also get the
+examples and the tutorials:
 
-  - ``cd kernel_tuner``  
-   
-- install using  
- 
-  - ``pip install .``  
+.. code-block:: bash
 
-Dependencies
-------------
-Python 2.7 or Python 3.5
-
-PyCuda and/or PyOpenCL (https://mathema.tician.de/software/)
-
-- To tune CUDA kernels
+    git clone https://github.com/benvanwerkhoven/kernel_tuner.git
+    cd kernel_tuner
+    pip install -r requirements.txt
+    pip install .
+    
+To tune CUDA kernels:
 
-  - Make sure you have the `CUDA Toolkit <https://developer.nvidia.com/cuda-toolkit>`_ installed 
-  - You can install PyCuda using ``pip install pycuda`` 
+  - First, make sure you have the `CUDA Toolkit <https://developer.nvidia.com/cuda-toolkit>`_ installed
+  - You can install PyCuda using ``pip install pycuda``
 
-- To tune OpenCL kernels
+To tune OpenCL kernels:
 
-  - Make sure you have an OpenCL compiler for your intended OpenCL platform
+  - First, make sure you have an OpenCL compiler for your intended OpenCL platform
   - You can install PyOpenCL using ``pip install pyopencl``
 
+If you need more information about how to install the Kernel Tuner and all dependencies see the `installation guide <http://benvanwerkhoven.github.io/kernel_tuner/install.html>`__
+
 Example usage
 -------------
 
@@ -96,7 +89,7 @@ The following shows a simple example for tuning a CUDA kernel:
     args = [c, a, b, n]
 
     tune_params = dict()
-    tune_params["block_size_x"] = [128+64*i for i in range(15)]
+    tune_params["block_size_x"] = [32, 64, 128, 256, 512]
 
     tune_kernel("vector_add", kernel_string, size, args, tune_params)
 
@@ -128,7 +121,7 @@ kernels and the scripts to tune them.
 Tuning host and kernel code
 ---------------------------
 
-It is also possible to tune for combinations of tunable parameters in
+It is possible to tune for combinations of tunable parameters in
 both host and kernel code. This allows for a number of powerfull things,
 such as tuning the number of streams for a kernel that uses CUDA Streams
 or OpenCL Command Queues to overlap transfers between host and device
@@ -152,33 +145,10 @@ expected output of the kernel. Input arguments are replaced with None.
     answer = [a+b, None, None]  # the order matches the arguments (in args) to the kernel
     tune_kernel("vector_add", kernel_string, size, args, tune_params, answer=answer)
 
-Contribution guide
-------------------
-
-The kernel tuner follows the Google Python style guide, with Sphinxdoc
-docstrings for module public functions. If you want to contribute to the
-project please fork it, create a branch including your addition, and
-create a pull request.
-
-The tests use relative imports and can be run directly after making
-changes to the code. To run all tests use ``nosetests`` in the main
-directory. To run the examples after code changes, you need to run
-``pip install --upgrade .`` in the main directory. Documentation is
-generated by typing ``make html`` in the doc directory, the contents of
-``doc/build/html/`` should then be copied to ``sphinxdoc`` directory of
-the ``gh-pages`` branch.
-
-Before creating a pull request please ensure the following:
-
-* You have written unit tests to test your additions and all unit tests pass
-* The examples still work and produce the same (or better) results
-* The code is compatible with both Python 2.7 and Python 3.5
-* An entry about the change or addition is created in CHANGELOG.md
-
-Contributing authors so far:
+Contributing
+------------
 
-* Ben van Werkhoven
-* Berend Weel
+Please see the `Contributions Guide <http://benvanwerkhoven.github.io/kernel_tuner/contributing.html>`__.
 
 Citation
 --------
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -59,9 +59,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'0.1.2'
+version = u'0.1.3'
 # The full version, including alpha/beta/rc tags.
-release = u'0.1.2'
+release = u'0.1.3'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst
@@ -0,0 +1,8 @@
+.. toctree::
+   :maxdepth: 2
+
+.. _contributing:
+
+
+.. include:: ../../CONTRIBUTING.rst
+
diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -12,6 +12,7 @@ Contents:
    :maxdepth: 1
 
    Introduction <self>
+   install
    examples
    tutorial
    convolution
@@ -20,6 +21,7 @@ Contents:
    hostcode
    user-api
    design
+   contributing
 
 Introduction
 ============
diff --git a/doc/source/install.rst b/doc/source/install.rst
@@ -0,0 +1,8 @@
+.. toctree::
+   :maxdepth: 2
+
+.. _install:
+
+
+.. include:: ../../INSTALL.rst
+
diff --git a/requirements-dev.txt b/requirements-dev.txt
@@ -0,0 +1,7 @@
+numpy>=1.7.1
+mock>=2.0.0
+nose>=1.3.7
+pytest>=3.0.3
+Sphinx>=1.4.8
+sphinx-rtd-theme>=0.1.9
+nbsphinx>=0.2.13
diff --git a/requirements.txt b/requirements.txt
@@ -1,7 +1 @@
 numpy>=1.7.1
-mock>=2.0.0
-nose>=1.3.7
-pytest>=3.0.3
-pycuda>=2016.1.1
-pyopencl>=2015.2.4
-
diff --git a/setup.py b/setup.py
