From 1f2081bf7da24704d6efdcc40e8ff9ffbe7116da Mon Sep 17 00:00:00 2001
From: Jens Schuppe <schuppe@systopia.de>
Date: Fri, 16 Nov 2018 11:54:18 +0100
Subject: [PATCH] Add a README and MKDocs documentation

---
 README.md     | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 docs/index.md |  1 +
 mkdocs.yml    | 19 ++++++++++++
 3 files changed, 102 insertions(+), 1 deletion(-)
 create mode 120000 docs/index.md
 create mode 100644 mkdocs.yml

diff --git a/README.md b/README.md
index 5f7fafe..93cf3f2 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,82 @@
-(* TODO *)
+# Twingle API
+
+Extension to connect to the Twingle fundraising service via its API.
+
+* [About Twingle](https://www.twingle.de/)
+
+The extension is licensed under
+[AGPL-3.0](https://github.com/systopia/de.systopia.twingle/blob/master/LICENSE.txt).
+
+## Configuration
+
+### Configure Twingle
+
+*This section is yet to be completed.*
+
+### Configure CiviCRM
+
+- Go to the Administration console `/civicrm/admin`
+- Open "Twingle API Configuration" at `/civicrm/admin/settings/twingle`
+
+#### Configure CiviSEPA integration
+
+Open "Configure extension settings" at
+`/civicrm/admin/settings/twingle/settings` and configure whether to integrate
+with the [CiviSEPA](https://github.com/project60/org.project60.sepa) extension.
+
+This enables you to map incoming donations from Twingle with a specific payment
+method (e.g. *debit_manual*) to be processed with CiviSEPA, that is, creating a
+SEPA mandate and managing recurring payments.
+
+#### Configure profiles
+
+Open "Configure profiles" at `/civicrm/admin/settings/twingle/profiles`.
+
+The *default* profile is used whenever the plugin cannot match the Twingle
+project ID from any other profile. Therefore the default profile will be used
+for all newly created Twingle projects.
+
+| Label                      | Description                                                                                                                                                  |
+|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Profile name               | Internal name, used inside the extension.                                                                                                                    |
+| Project IDs                | Twingle project IDs. Separate multiple IDs with commas.                                                                                                      |
+| Location type              | Specify how the address data sent by the form should be categorised in CiviCRM. The list is based on your CiviCRM configuration.                             |
+| Financial type             | Specify which financial type incoming donations should be recorded with in CiviCRM. The list is based on your CiviCRM configuration.                         |
+| Gender options             | Specify which CiviCRM gender option the incoming Twingle gender value should be mapped to. The list is based on your CiviCRM configuration.                  |
+| Record *Payment method* as | Specifiy the payment methods mapping for incoming donations for each Twingle payment method.                                                                 |
+| CiviSEPA creditor          | When enabled to integrate with CiviSEPA, specify the CiviSEPA creditor to use.                                                                               |
+| Sign up for groups         | Whenever the donor checked the newsletter/postal mailing/donation receipt checkbox on the Twingle form, the contact will be added to the groups listed here. |
+
+
+## API documentation
+
+The extension provides a new CiviCRM API entity `TwingleDonation` with API
+actions to record a new donation, end a previously submitted recurring donation
+and cancel previously submitted donation.
+
+### Submit donation
+
+- Entity: `TwingleDonation`
+- Action: `Submit`
+
+*This section is to be completed: Add parameters documentation and describe what
+the action does. In the meantime, refer to
+[the code](https://github.com/systopia/de.systopia.twingle/blob/master/api/v3/TwingleDonation/Submit.php)*
+
+### End recurring donation
+
+- Entity: `TwingleDonation`
+- Action: `EndRecurring`
+
+*This section is to be completed: Add parameters documentation and describe what
+the action does. In the meantime, refer to
+[the code](https://github.com/systopia/de.systopia.twingle/blob/master/api/v3/TwingleDonation/EndRecurring.php)*
+
+### Cancel donation
+
+- Entity: `TwingleDonation`
+- Action: `Cancel`
+
+*This section is to be completed: Add parameters documentation and describe what
+the action does. In the meantime, refer to
+[the code](https://github.com/systopia/de.systopia.twingle/blob/master/api/v3/TwingleDonation/Cancel.php)*
diff --git a/docs/index.md b/docs/index.md
new file mode 120000
index 0000000..32d46ee
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1 @@
+../README.md
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..dc51ca6
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,19 @@
+site_name: Twingle API
+repo_url: https://github.com/systopia/de.systopia.twingle
+theme: material
+
+pages:
+- 'Home': index.md
+
+markdown_extensions:
+- attr_list
+- admonition
+- def_list
+- codehilite
+- toc:
+    permalink: true
+- pymdownx.superfences
+- pymdownx.inlinehilite
+- pymdownx.tilde
+- pymdownx.betterem
+- pymdownx.mark