# HG changeset patch
# User Andrey Lebedev <andrey@lebedev.lt>
# Date 1383400545 -7200
# Node ID 103ad506a83d45ace977a87efc185596639746c5
# Parent  1f85ed8ed469d2570cb7e109b9e49b05310b1999
More detailed docs on creating ofxstatement plugins

diff -r 1f85ed8ed469 -r 103ad506a83d README.rst
--- a/README.rst	Sat Nov 02 14:26:03 2013 +0200
+++ b/README.rst	Sat Nov 02 15:55:45 2013 +0200
@@ -15,3 +15,76 @@
 Users of ofxstatement have developed several plugins for their banks. They are
 listed on main `ofxstatement`_ site. If your bank is missing, you can develop
 your own plugin.
+
+Setting up development environment
+==================================
+
+It is recommended to use ``virtualenv`` make a clean development environment.
+Setting up dev environment for writing a plugin is easy::
+
+  $ git clone https://github.com/kedder/ofxstatement-sample ofxstatement-  yourbank
+  $ cd ofxstatement-yourbank
+  $ virtualenv -p python3 --no-site-packages .venv
+  $ . .venv/bin/activate
+  (.venv)$ python setup.py develop
+
+This will download all the dependencies and install them into your virtual
+environment. After this, you should be able to do::
+
+  (.venv)$ ofxstatement list-plugins
+  The following plugins are available:
+
+    sample           Sample plugin (for developers only)
+
+
+
+Your own plugin
+===============
+
+To create your own plugin, follow these steps:
+
+* Edit ``setup.py`` and provide relevant metadata for your plugin.  Pay
+  close attention to ``entry_points`` parameter to ``setup`` function: it
+  lists plugins you are registering within ofxstatement. Give meaningful
+  name to the plugin and provide plugin class name
+* Replace contents of ``README.rst`` with description of your plugin
+* Rename ``ofxstatement/plugins/sample.py`` to match plugin package name
+  you have provided in ``entry_points`` parameter.
+* Open renamed sample.py and rename ``SamplePlugin`` and ``SampleParser``
+  classes to match your plugin class name.
+* Now, draw the rest of the owl (c).
+
+.. _ofxstatement-sample: https://github.com/kedder/ofxstatement-sample
+
+Your ``StatementParser`` is the main object that does all the hard work. It
+has only one public method: ``parse()``, that should return
+``ofxstatement.statement.Statement`` object, filled with data from given input.
+The default implementation, however, splits this work into two parts:
+``split_records()`` to split the whole file into logical parts, e.g.
+transaction records, and ``parse_record()`` to extract information from
+individual record. See ``src/ofxstatement/parser.py`` for details. If your
+statement' format looks like CSV file, you might find ``CsvStatementParser``
+class useful: it simplifies mapping bettween CSV columns and ``StatementLine``
+attributes.
+
+``Plugin`` interface consists only of ``get_parser()`` method, that returns
+configured StatementParser object for given input filename. Docstrings on
+Plugin class is also useful for describing the purpose of your plugin. First
+line of it is visible in ``ofxstatement list-plugins`` output.
+
+Testing
+=======
+
+Test your code as you would do with any other project.  To make sure
+ofxstatement is still able to load your plugin, run::
+
+  (.venv)$ ofxstatement list-plugins
+
+You should be able to see your plugin listed.
+
+After you are done
+==================
+
+After your plugin is ready, feel free to open an issue on `ofxstatement`_
+project to include your plugin in "known plugin list". That would hopefully
+make life of other clients of your bank easier.