Add plugin documentation

doc/conf.py

@@ -38,6 +38,7 @@ extensions = [
     'sphinx.ext.doctest',
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
+    'sphinxcontrib.httpdomain',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

doc/development/implementation/models.rst

@@ -64,6 +64,9 @@ Carts and Orders
    :members:
 
 .. autoclass:: pretix.base.models.QuestionAnswer
+:members:
+
+.. autoclass:: pretix.base.models.Checkin
    :members:
 
 Logging

doc/index.rst

@@ -8,4 +8,5 @@ Contents:
 
    admin/index
    development/index
+   plugins/index
 

doc/plugins/index.rst

@@ -0,0 +1,13 @@
+Plugin documentation
+====================
+
+This part of the documentation contains information about available plugins
+that can be used to extend pretix's functionality.
+If you want to **create** a plugin, please go to the
+:ref:`Developer documentation <pluginsetup>` instead.
+
+.. toctree::
+   :maxdepth: 2
+
+   list
+   pretixdroid

doc/plugins/list.rst

@@ -0,0 +1,30 @@
+List of plugins
+===============
+
+The following plugins are shipped with pretix and are supported in the same
+ways that pretix itself is:
+
+* Bank transfer
+* PayPal
+* Stripe
+* Check-in lists
+* pretixdroid
+* Report exporter
+* Send out emails
+* Statistics
+* PDF ticket output
+
+The following plugins are not shipped with pretix but are maintained by the
+same team:
+
+* `Passbook/Wallet ticket output`_
+* `Cartshare`_
+
+The following plugins are from independent third-party authors, so we can make
+no statements about their stability:
+
+* `esPass ticket output`_
+
+.. _Passbook/Wallet ticket output: https://github.com/pretix/pretix-passbook
+.. _Cartshare: https://github.com/pretix/pretix-cartshare
+.. _esPass ticket output: https://github.com/esPass/pretix-espass

doc/plugins/pretixdroid.rst

@@ -0,0 +1,100 @@
+pretixdroid HTTP API
+====================
+
+The pretixdroid plugin provides a HTTP API that the `pretixdroid Android app`_
+uses to communicate with the pretix server.
+
+.. http:post:: /pretixdroid/api/(organizer)/(event)/redeem/
+
+   Redeems a ticket, i.e. checks the user in.
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      POST /pretixdroid/api/demoorga/democon/redeem/?key=ABCDEF HTTP/1.1
+      Host: demo.pretix.eu
+      Accept: application/json, text/javascript
+      Content-Type: application/x-www-form-urlencoded
+
+      secret=az9u4mymhqktrbupmwkvv6xmgds5dk3
+
+   **Example successful response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: text/json
+
+      {
+        'status': 'ok'
+        'version': 2
+      }
+
+   **Example error response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: text/json
+
+      {
+        'status': 'error',
+        'reason': 'already_redeemed',
+        'version': 2
+      }
+
+   Possible error reasons:
+
+   * ``unpaid`` - Ticket is not paid for or has been refunded
+   * ``already_redeemed`` - Ticket already has been redeemed
+   * ``unknown_ticket`` - Secret does not match a ticket in the database
+
+   :query key: Secret API key
+         :statuscode 200: Valid request
+         :statuscode 404: Unknown organizer or event
+         :statuscode 403: Invalid authorization key
+
+.. http:get:: /pretixdroid/api/(organizer)/(event)/search/
+
+   Searches for a ticket.
+   At most 25 results will be returned. **Queries with less than 4 characters will always return an empty result set.**
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      GET /pretixdroid/api/demoorga/democon/search/?key=ABCDEF&query=Peter HTTP/1.1
+      Host: demo.pretix.eu
+      Accept: application/json, text/javascript
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: text/json
+
+      {
+        'results': [
+          {
+            'secret': 'az9u4mymhqktrbupmwkvv6xmgds5dk3',
+            'order': 'ABCE6',
+            'item': 'Standard ticket',
+            'variation': null,
+            'attendee_name': 'Peter Higgs',
+            'redeemed': false,
+            'paid': true
+          },
+          ...
+        ],
+        'version': 2
+      }
+
+   :query query: Search query
+   :query key: Secret API key
+   :statuscode 200: Valid request
+   :statuscode 404: Unknown organizer or event
+   :statuscode 403: Invalid authorization key
+
+.. _pretixdroid Android app: https://github.com/pretix/pretixdroid

doc/requirements.txt

@@ -1,3 +1,4 @@
 -r ../src/requirements.txt
 sphinx
 sphinx-rtd-theme
+sphinxcontrib-httpdomain

src/pretix/base/models/checkin.py

@@ -2,5 +2,8 @@ from django.db import models
 
 
 class Checkin(models.Model):
+    """
+    A checkin object is created when a person enters the event.
+    """
     position = models.ForeignKey('pretixbase.OrderPosition', related_name='pretixdroid_checkins')
     datetime = models.DateTimeField(auto_now_add=True)