From 5dbd335ac6c163c743cd7ac824b88e0c7235fe29 Mon Sep 17 00:00:00 2001
From: Nick Moore <nick@zoic.org>
Date: Wed, 25 Oct 2023 20:51:04 +1100
Subject: [PATCH] start on github pages docs

---
 docs/config-file-format/index.md  |  0
 docs/index.md                     | 19 +++++--
 docs/installing-countess/index.md | 25 ++++++++++
 docs/writing-plugins/index.md     | 82 +++++++++++++++++++++++++++++++
 4 files changed, 123 insertions(+), 3 deletions(-)
 create mode 100644 docs/config-file-format/index.md
 create mode 100644 docs/installing-countess/index.md
 create mode 100644 docs/writing-plugins/index.md

diff --git a/docs/config-file-format/index.md b/docs/config-file-format/index.md
new file mode 100644
index 0000000..e69de29
diff --git a/docs/index.md b/docs/index.md
index f22cd65..60634bd 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,7 +1,20 @@
 # CountESS Documentation
 
-[Github Repository](https://github.com/CountESS-Project/CountESS/)
+This is CountESS, a modular, Python 3 reimplementation of Enrich2.
 
-Documentation:
+[Source code is available](https://github.com/CountESS-Project/CountESS)
+and contributions are welcomed.
+
+[This documentation is generated](https://github.com/CountESS-Project/CountESS/tree/main/docs)
+from the `/docs/` directory and documentation fixes are also welcomed!
+
+## Documentation
+
+* [Installing CountESS](installing-countess/)
+* [Writing Plugins](writing-plugins/)
+* [Configuration File Format](config-file-format/)
+
+## Presentations
+
+* [CountESS: Count-based Experimental Scoring and Statistics](https://www.youtube.com/watch?v=JzU6cbvZ0a0) at [PyConAU 2023](https://2023.pycon.org.au/)
 
-* [plugins](plugins/)
diff --git a/docs/installing-countess/index.md b/docs/installing-countess/index.md
new file mode 100644
index 0000000..547541e
--- /dev/null
+++ b/docs/installing-countess/index.md
@@ -0,0 +1,25 @@
+## Installing CountESS
+
+CountESS can be installed from pypi:
+```
+pip install CountESS
+```
+
+... or install the latest development version directly from github:
+```
+pip install git+https://github.com/CountESS-Project/CountESS.git
+```
+
+... or download and install for development:
+```
+git clone https://github.com/CountESS-Project/CountESS.git
+cd CountESS
+pip install -e .
+```
+
+... or run with nix:
+```
+nix run github:CountESS-Project/CountESS
+```
+
+
diff --git a/docs/writing-plugins/index.md b/docs/writing-plugins/index.md
new file mode 100644
index 0000000..050737f
--- /dev/null
+++ b/docs/writing-plugins/index.md
@@ -0,0 +1,82 @@
+# Writing CountESS Plugins
+
+CountESS is a framework which connects together many components which do the actual
+work, these components are called Plugins.  
+
+There are many plugins supplied as part of CountESS but it is also very easy to 
+write your own.
+
+## General Structure
+
+Plugins are provided by Python classes.
+All CountESS plugin classes are required to be subclasses of
+`countess.core.plugins.BasePlugin`.
+
+CountESS detects installed plugins using the
+[Python `importlib.metadata.entry_points`](https://docs.python.org/3/library/importlib.metadata.html#entry-points)
+mechanism.  So to declare your new class as a CountESS plugin, you
+just need to add a clause like this to your `pyproject.toml` or
+equivalent:
+
+```
+[project.entry-points.countess_plugins]
+myplugin = "myproject:MyPluginClass"
+```
+
+## Types of Plugin
+
+The most common kind of plugin takes a pandas dataframe, transforms it,
+and passes the transformed dataframe along to the next plugin.
+
+Examples include the Expression plugin, which creates a new column by
+applying a formula to the existing columns, or the Regex Tool plugin which 
+uses a regular expression to break an existing column into multiple
+parts.
+
+Other types of plugin include readers, which read from a file in
+some particular format, and writers, which write formatted data.
+
+## Configuration Parameters
+
+Plugins have "configuration parameters" which are declared in the plugin
+class declaration using subclasses of `countess.core.parameters.BaseParameter`.
+
+Configfuration values are provided by a [single configuration file which
+is read and written by CountESS](../config-file-format/)
+
+## Subclassing `BasePlugin`
+
+To make life easier, there are several subclasses of `BasePlugin`
+under `countess.core.plugins` ... each of these provides common 
+features used in different types of plugins.
+
+### PandasSimplePlugin
+
+### PandasTransform**X**To**Y**Plugin
+
+There are several classes of the form `PandasTransform`**X**`To`**Y**`Plugin`.
+
+The most obviously useful ones are `PandasTransformSingleToSinglePlugin`, 
+which translates a single value into another single value, and 
+`PandasTransformDictToDictPlugin`, which translates an entire table row.
+
+To use these classes, subclass the appropriate one for your plugin and 
+override `process_value`, `process_row` or `process_dict` as appropriate.
+
+
+## Built-in Plugins
+
+### `LoadCSVPlugin`
+
+### `LoadHdfPlugin`
+
+### `LoadFastqPlugin`
+
+### `LogScorePlugin`
+
+### `GroupByPlugin`
+
+## Example Plugins
+
+Under [example-plugins](../example-plugins/) are files showing the 
+suggested layout for Python code in a plugin.