Swappable invoice renderers

doc/development/api/index.rst

@@ -10,5 +10,6 @@ Contents:
    exporter
    ticketoutput
    payment
+   invoice
    customview
    general

doc/development/api/invoice.rst

@@ -0,0 +1,95 @@
+.. highlight:: python
+   :linenothreshold: 5
+
+Writing an invoice renderer plugin
+==================================
+
+An invoice renderer controls how invoice files are built.
+The creation of such a plugin is very similar to creating an export output.
+
+Please read :ref:`Creating a plugin <pluginsetup>` first, if you haven't already.
+
+Output registration
+-------------------
+
+The invoice renderer API does not make a lot of usage from signals, however, it
+does use a signal to get a list of all available ticket outputs. Your plugin
+should listen for this signal and return the subclass of ``pretix.base.invoice.BaseInvoiceRenderer``
+that we'll provide in this plugin::
+
+    from django.dispatch import receiver
+
+    from pretix.base.signals import register_invoice_renderers
+
+
+    @receiver(register_invoice_renderers, dispatch_uid="output_custom")
+    def register_infoice_renderers(sender, **kwargs):
+        from .invoice import MyInvoiceRenderer
+        return MyInvoiceRenderer
+
+
+The renderer class
+------------------
+
+.. class:: pretix.base.invoice.BaseInvoiceRenderer
+
+   The central object of each invoice renderer is the subclass of ``BaseInvoiceRenderer``.
+
+   .. py:attribute:: BaseInvoiceRenderer.event
+
+      The default constructor sets this property to the event we are currently
+      working for.
+
+   .. autoattribute:: identifier
+
+      This is an abstract attribute, you **must** override this!
+
+   .. autoattribute:: verbose_name
+
+      This is an abstract attribute, you **must** override this!
+
+   .. automethod:: generate
+
+Helper class for reportlab-base renderers
+-----------------------------------------
+
+All PDF rendering that ships with pretix is based on reportlab. We recommend to read the
+`reportlab User Guide`_ to understand all the concepts used here.
+
+If you want to implement a renderer that also uses report lab, this helper class might be
+convenient to you:
+
+
+.. class:: pretix.base.invoice.BaseReportlabInvoiceRenderer
+
+   .. py:attribute:: BaseReportlabInvoiceRenderer.pagesize
+
+   .. py:attribute:: BaseReportlabInvoiceRenderer.left_margin
+
+   .. py:attribute:: BaseReportlabInvoiceRenderer.right_margin
+
+   .. py:attribute:: BaseReportlabInvoiceRenderer.top_margin
+
+   .. py:attribute:: BaseReportlabInvoiceRenderer.bottom_margin
+
+   .. py:attribute:: BaseReportlabInvoiceRenderer.doc_template_class
+
+   .. py:attribute:: BaseReportlabInvoiceRenderer.invoice
+
+   .. automethod:: _init
+
+   .. automethod:: _get_stylesheet
+
+   .. automethod:: _register_fonts
+
+   .. automethod:: _on_first_page
+
+   .. automethod:: _on_other_page
+
+   .. automethod:: _get_first_page_frames
+
+   .. automethod:: _get_other_page_frames
+
+   .. automethod:: _build_doc
+
+.. _reportlab User Guide: https://www.reportlab.com/docs/reportlab-userguide.pdf