plugins/tutorial.md

+# Tutorial
+
+
+In the simplest case you inherit the appropriate interface class from ``owscaling/plugins.py`` and override the following properties/methods in your plug-in:
+
+* ``name`` property,
+* ``__version__`` property,
+* ``__copyright__`` property,
+* ``ArgumentParser`` property,
+* ``__init__()`` method,
+* ``__str__()`` method and
+* ``__call__()`` method.
+
+
+We will explain, how this is done in the following examples:
+
+* [Example 1](./tutorial/example_1): Constant viscosity
+* [Example 2](./tutorial/example_2): Specify viscosity at the command line
+* [Example 3](./tutorial/example_3): Viscosity as a function of the temperature
+* [Example 4](./tutorial/example_4): Viscosity as a function of the temperature, user supplied coefficients
+
+
+We will start with an easy case and get (slightly) more complicating when we implement more features.
+
+Files
+-----
+In all cases you will write a Python file, so start your favourite editor and put the following preamble at the top of a new file:
+```python
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+My very first plug-in implementing the `IViscosityPlugin` interface.
+
+Plug-ins:
+    MyConstant:
+        Constant kinematic viscosity of a fluid.
+
+
+Created on Thu Feb  2 16:17:00 2017
+
+
+Copyright (C) 2017  Stephan Helma
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any later
+version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with
+this program. If not, see <http://www.gnu.org/licenses/>.
+"""
+```
+
+#### Notes
+
+1. We start the file with the magic line ``#!/usr/bin/env python3``. (Please keep it there, even if you program in Windows). This is followed by the encoding of the file (in our case UTF-8), which any respectable editor should honour.
+2. Following the [Style Guide for Python Code,](https://www.python.org/dev/peps/pep-0008/) we describe what the file does in one line in the docstring and then we add a list of the plug-ins implemented in this file (often this is just one plug-in, but can be more than one).
+3. At the bottom add the copyright information. This should be the copyright of the program and not the copyright of the underlying theory (we will come to that). It should include the author who coded the program (and not the author of the theory behind it).