mirror of
https://github.com/pretix/pretix.git
synced 2026-08-14 11:26:26 +00:00
Various docs improvements
This commit is contained in:
Raphael Michel
+2
-2
@@ -1,10 +1,10 @@
|
||||
.. _`admindocs`:
|
||||
|
||||
Administrator documentation
|
||||
===========================
|
||||
|
||||
This documentation is for everyone who wants to install pretix on a server.
|
||||
|
||||
Contents:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
Plugin hooks
|
||||
============
|
||||
Plugin development
|
||||
==================
|
||||
|
||||
Contents:
|
||||
|
||||
|
||||
@@ -1,8 +1,10 @@
|
||||
.. highlight:: python
|
||||
:linenothreshold: 5
|
||||
|
||||
Plugin basics
|
||||
=============
|
||||
.. _`pluginsetup`:
|
||||
|
||||
Creating a plugin
|
||||
=================
|
||||
|
||||
It is possible to extend pretix with custom Python code using the official plugin
|
||||
API. Every plugin has to be implemented as an independent Django 'app' living
|
||||
@@ -14,10 +16,15 @@ The communication between pretix and the plugins happens mostly using Django's
|
||||
``pretix.control`` and ``pretix.presale`` expose a number of signals which are documented
|
||||
on the next pages.
|
||||
|
||||
.. _`pluginsetup`:
|
||||
|
||||
To create a new plugin, create a new python package which must be a valid `Django app`_
|
||||
and must contain plugin metadata, as described below.
|
||||
There is some boilerplate that you will need for every plugin to get started. To save your
|
||||
time, we created a `cookiecutter`_ template that you can use like this::
|
||||
|
||||
$ pip install cookiecutter
|
||||
$ cookiecutter https://github.com/pretix/pretix-plugin-cookiecutter
|
||||
|
||||
This will ask you some questions and then create a project folder for your plugin.
|
||||
|
||||
The following pages go into detail about the several types of plugins currently
|
||||
supported. While these instructions don't assume that you know a lot about pretix,
|
||||
@@ -30,35 +37,29 @@ Plugin metadata
|
||||
The plugin metadata lives inside a ``PretixPluginMeta`` class inside your app's
|
||||
configuration class. The metadata class must define the following attributes:
|
||||
|
||||
``name`` (``str``):
|
||||
The human-readable name of your plugin
|
||||
.. rst-class:: rest-resource-table
|
||||
|
||||
``author`` (``str``):
|
||||
Your name
|
||||
|
||||
``version`` (``str``):
|
||||
A human-readable version code of your plugin
|
||||
|
||||
``description`` (``str``):
|
||||
A more verbose description of what your plugin does.
|
||||
|
||||
``visible`` (``bool``):
|
||||
``True`` by default, can hide a plugin so it cannot be normally activated.
|
||||
|
||||
``restricted`` (``bool``):
|
||||
``False`` by default, restricts a plugin such that it can only be enabled for an event
|
||||
by system administrators / superusers.
|
||||
================== ==================== ===========================================================
|
||||
Attribute Type Description
|
||||
================== ==================== ===========================================================
|
||||
name string The human-readable name of your plugin
|
||||
author string Your name
|
||||
version string A human-readable version code of your plugin
|
||||
description string A more verbose description of what your plugin does.
|
||||
visible boolean (optional) ``True`` by default, can hide a plugin so it cannot be normally activated.
|
||||
restricted boolean (optional) ``False`` by default, restricts a plugin such that it can only be enabled
|
||||
for an event by system administrators / superusers.
|
||||
================== ==================== ===========================================================
|
||||
|
||||
A working example would be::
|
||||
|
||||
# file: pretix/plugins/timerestriction/__init__.py
|
||||
from django.apps import AppConfig
|
||||
from django.utils.translation import ugettext_lazy as _
|
||||
|
||||
|
||||
class PaypalApp(AppConfig):
|
||||
name = 'pretix.plugins.paypal'
|
||||
verbose_name = _("Stripe")
|
||||
name = 'pretix_paypal'
|
||||
verbose_name = _("PayPal")
|
||||
|
||||
class PretixPluginMeta:
|
||||
name = _("PayPal")
|
||||
@@ -69,8 +70,7 @@ A working example would be::
|
||||
description = _("This plugin allows you to receive payments via PayPal")
|
||||
|
||||
|
||||
default_app_config = 'pretix.plugins.paypal.PaypalApp'
|
||||
|
||||
default_app_config = 'pretix_paypal.PaypalApp'
|
||||
|
||||
The ``AppConfig`` class may implement a property ``compatiblity_errors``, that checks
|
||||
whether the pretix installation meets all requirements of the plugin. If so,
|
||||
@@ -87,11 +87,10 @@ make use of the `entry point`_ feature of setuptools. To register a plugin that
|
||||
in a separate python package, your ``setup.py`` should contain something like this::
|
||||
|
||||
setup(
|
||||
…
|
||||
|
||||
args...,
|
||||
entry_points="""
|
||||
[pretix.plugin]
|
||||
sampleplugin=sampleplugin:PretixPluginMeta
|
||||
pretix_paypal=pretix_paypal:PretixPluginMeta
|
||||
"""
|
||||
)
|
||||
|
||||
@@ -109,7 +108,7 @@ pages. We suggest that you put your signal receivers into a ``signals`` submodul
|
||||
of your plugin. You should extend your ``AppConfig`` (see above) by the following
|
||||
method to make your receivers available::
|
||||
|
||||
class TimeRestrictionApp(AppConfig):
|
||||
class PaypalApp(AppConfig):
|
||||
…
|
||||
|
||||
def ready(self):
|
||||
@@ -131,3 +130,4 @@ your Django app label.
|
||||
.. _signal dispatcher: https://docs.djangoproject.com/en/1.7/topics/signals/
|
||||
.. _namespace packages: http://legacy.python.org/dev/peps/pep-0420/
|
||||
.. _entry point: https://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins
|
||||
.. _cookiecutter: https://cookiecutter.readthedocs.io/en/latest/
|
||||
|
||||
@@ -1,18 +1,16 @@
|
||||
Implementation concepts
|
||||
=======================
|
||||
|
||||
Basic terminology
|
||||
-----------------
|
||||
Concepts and Terminology
|
||||
========================
|
||||
|
||||
The components
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
The project pretix is split into several components. The main three of them are:
|
||||
The project pretix is split into several components. The main components are:
|
||||
|
||||
**base**
|
||||
This is the foundation below all other components. It is primarily
|
||||
responsible for the data structures and database communication. It also hosts
|
||||
several utilities which are used by multiple other components.
|
||||
several utilities which are used by multiple other components and important parts of
|
||||
the business logic.
|
||||
|
||||
**control**
|
||||
This is the web-based backend software which allows organizers to
|
||||
@@ -20,7 +18,13 @@ The project pretix is split into several components. The main three of them are:
|
||||
|
||||
**presale**
|
||||
This is the ticket-shop itself, containing all of the parts visible to the
|
||||
end user.
|
||||
end user. Also called "frontend" in parts of this documentation.
|
||||
|
||||
**api**
|
||||
A RESTful API exposed to integrate with third-party software.
|
||||
|
||||
**plugins**
|
||||
A set of pretix plugins that ship bundled with pretix.
|
||||
|
||||
Users and events
|
||||
^^^^^^^^^^^^^^^^
|
||||
@@ -61,6 +65,7 @@ limit:
|
||||
* The number of orders placed for an item that are either already paid or within their granted payment period
|
||||
* The number of non-expired items currently in the shopping cart of users
|
||||
* The number of vouchers defined as "quota blocking" (see blow)
|
||||
* The number of people on the waiting list
|
||||
|
||||
The quota system tries very hard to be as friendly as possible to your event attendees while still making sure
|
||||
your limit is never exceeded. For example, when the payment period of an order expires without the order being
|
||||
|
||||
@@ -9,7 +9,8 @@ constructive and friendly feedback on your changes.
|
||||
First of all, you'll need pretix running locally on your machine. Head over to :ref:`devsetup` to learn how to do this.
|
||||
If you run into any problems on your way, please do not hesitate to ask us anytime!
|
||||
|
||||
Please note that we have a :ref:`coc` in place that applies to all communication around the project.
|
||||
Please note that we bound ourselves to a :ref:`coc` that applies to all communication around the project. You can be
|
||||
assured that we will not tolerate any form of harassment.
|
||||
|
||||
Sending a patch
|
||||
---------------
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
Contribution guide
|
||||
==================
|
||||
Contributing to pretix
|
||||
======================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
@@ -1,39 +1,30 @@
|
||||
Coding style
|
||||
============
|
||||
Coding style and quality
|
||||
========================
|
||||
|
||||
Python code
|
||||
-----------
|
||||
* Basically, we want all python code to follow the `PEP 8`_ standard. There are a few exceptions where
|
||||
we see things differently or just aren't that strict. The ``setup.cfg`` file in the project's source
|
||||
folder contains definitions that allow `flake8`_ to check for violations automatically. See :ref:`checksandtests`
|
||||
for more information. Use four spaces for indentation.
|
||||
|
||||
* Basically: Follow `PEP 8`_.
|
||||
* We sort our imports by a certain schema, but you don't have to do this by hand. Again, ``setup.cfg`` contains
|
||||
some definitions that allow the command ``isort -rc <directory>`` to automatically sort the imports in your source
|
||||
files.
|
||||
|
||||
Use `flake8`_ to check for conformance problems. The project includes a setup.cfg file
|
||||
with a default configuration for flake8 that excludes migrations and other non-relevant
|
||||
code parts. It also silences a few checks, e.g. ``N802`` (function names should be lowercase)
|
||||
and increases the maximum line length to more than 79 characters. **However** you should
|
||||
still name all your functions lowercase [#f1]_ and keep your lines short when possible.
|
||||
* For templates and models, please take a look at the `Django Coding Style`_. We like Django's `class-based views`_ and
|
||||
kindly ask you to use them where appropriate.
|
||||
|
||||
* Our build server will reject all code violating other flake8 checks than the following:
|
||||
* Please remember to always mark all strings ever displayed to any user for `translation`_.
|
||||
|
||||
* E123: closing bracket does not match indentation of opening bracket’s line
|
||||
* F403: ``from module import *`` used; unable to detect undefined names
|
||||
* F401: module imported but unused
|
||||
* N802: function names should be lowercase
|
||||
|
||||
So please make sure that you *always* follow all other rules and break these rules *only when
|
||||
it makes sense*.
|
||||
|
||||
* Use ``isort -rc pretix`` in the source directory to order your imports.
|
||||
|
||||
* Indent your code with four spaces.
|
||||
|
||||
* For templates and models, follow the `Django Coding Style`_.
|
||||
|
||||
* Use Django's class-based views
|
||||
|
||||
* Always mark all strings ever displayed to any user for translation.
|
||||
* We expect all new code to come with proper tests. When writing new tests, please write them using `pytest-style`_
|
||||
test functions and raw ``assert`` statements. Use `fixtures`_ to prevent repetitive code. Some old parts of pretix'
|
||||
test suite are in the style of Python's unit test module. If you extend those files, you might continue in this style,
|
||||
but please use pytest style for any new test files.
|
||||
|
||||
|
||||
.. _PEP 8: http://legacy.python.org/dev/peps/pep-0008/
|
||||
.. _flake8: https://pypi.python.org/pypi/flake8
|
||||
.. _Django Coding Style: https://docs.djangoproject.com/en/dev/internals/contributing/writing-code/coding-style/
|
||||
.. [#f1] But Python's very own ``unittest`` module forces us to use ``setUp`` as a method name...
|
||||
.. _translation: https://docs.djangoproject.com/en/1.11/topics/i18n/translation/
|
||||
.. _class-based views: https://docs.djangoproject.com/en/1.11/topics/class-based-views/
|
||||
.. _pytest-style: https://docs.pytest.org/en/latest/assert.html
|
||||
.. _fixtures: https://docs.pytest.org/en/latest/fixture.html
|
||||
|
||||
@@ -6,10 +6,10 @@ Developer documentation
|
||||
|
||||
concepts
|
||||
setup
|
||||
structure
|
||||
contribution/index
|
||||
implementation/index
|
||||
api/index
|
||||
structure
|
||||
|
||||
.. TODO::
|
||||
Document settings objects, ItemVariation objects, form fields.
|
||||
|
||||
@@ -1,7 +1,11 @@
|
||||
.. _`devsetup`:
|
||||
|
||||
The development setup
|
||||
=====================
|
||||
Development setup
|
||||
=================
|
||||
|
||||
This tutorial helps you to get started hacking with pretix on your own computer. You need this to
|
||||
be able to contribute to pretix, but it might also be helpful if you want to write your own plugins.
|
||||
If you want to install pretix on a server for actual usage, go to the :ref:`admindocs` instead.
|
||||
|
||||
Obtain a copy of the source code
|
||||
--------------------------------
|
||||
@@ -12,6 +16,8 @@ You can just clone our git repository::
|
||||
|
||||
External Dependencies
|
||||
---------------------
|
||||
Your should install the following on your system:
|
||||
|
||||
* Python 3.4 or newer
|
||||
* ``pip`` for Python 3 (Debian package: ``python3-pip``)
|
||||
* ``pyvenv`` for Python 3 (Debian package: ``python3-venv``)
|
||||
@@ -49,7 +55,7 @@ The first thing you need are all the main application's dependencies::
|
||||
cd src/
|
||||
pip3 install -r requirements.txt -r requirements/dev.txt
|
||||
|
||||
If you are working with Python 3.4, you will also need (you can skip this for Python 3.5)::
|
||||
If you are working with Python 3.4, you will also need (you can skip this for Python 3.5+)::
|
||||
|
||||
pip3 install -r requirements/py34.txt
|
||||
|
||||
@@ -91,11 +97,18 @@ data as suggested above, to the event page at http://localhost:8000/bigevents/20
|
||||
|
||||
Code checks and unit tests
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Before you check in your code into git, always run the static checkers and unit tests::
|
||||
Before you check in your code into git, always run static checkers and linters. If any of these commands fail,
|
||||
your pull request will not be merged into pretix. If you have trouble figuring out *why* they fail, create your
|
||||
pull request nevertheless and ask us for help, we are happy to assist you.
|
||||
|
||||
Execute the following commands to check for code style errors::
|
||||
|
||||
flake8 .
|
||||
isort -c -rc .
|
||||
python manage.py check
|
||||
|
||||
Execute the following command to run pretix' test suite (might take a coumple of minutes)::
|
||||
|
||||
py.test
|
||||
|
||||
.. note:: If you have multiple CPU cores and want to speed up the test suite, you can install the python
|
||||
@@ -107,9 +120,10 @@ for example::
|
||||
|
||||
#!/bin/sh
|
||||
cd $GIT_DIR/../src
|
||||
source ../env/bin/activate
|
||||
flake8 --ignore=E123,E128,F403,F401,N802,W503 .
|
||||
flake8 . || exit 1
|
||||
isort -q -rc -c . || exit 1
|
||||
|
||||
This keeps you from accidentally creating commits violating the sdtyle guide.
|
||||
|
||||
Working with mails
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
@@ -151,8 +165,14 @@ To build the documentation, run the following command from the ``doc/`` director
|
||||
|
||||
make html
|
||||
|
||||
You will now find the generated documentation in the ``doc/_build/html/`` subdirectory.
|
||||
You will now find the generated documentation in the ``doc/_build/html/`` subdirectory. If you work
|
||||
with the documentation a lot, you might find it useful to use sphinx-autobuild::
|
||||
|
||||
pip3 install sphinx-autobuild
|
||||
sphinx-autobuild . _build/html -p 8081
|
||||
|
||||
Then, go to http://localhost:8081 for a version of the documentation that automatically re-builds
|
||||
whenever you change a source file.
|
||||
|
||||
.. _Django's documentation: https://docs.djangoproject.com/en/1.11/ref/django-admin/#runserver
|
||||
.. _pretixdroid: https://github.com/pretix/pretixdroid
|
||||
|
||||
@@ -1,13 +1,10 @@
|
||||
Project structure
|
||||
=================
|
||||
|
||||
Python source code
|
||||
------------------
|
||||
Directory structure
|
||||
===================
|
||||
|
||||
All the source code lives in ``src/``, which has several subdirectories.
|
||||
|
||||
pretix/
|
||||
This directory contains nearly all source code.
|
||||
This directory contains nearly all source code that belongs to pretix.
|
||||
|
||||
base/
|
||||
This is the Django app containing all the models and methods which are
|
||||
@@ -19,48 +16,31 @@ pretix/
|
||||
presale/
|
||||
This is the Django app containing the front end for users buying tickets.
|
||||
|
||||
api/
|
||||
This is the Django app containing all views and serializers for pretix'
|
||||
:ref:`rest-api`.
|
||||
|
||||
helpers/
|
||||
Helpers contain a very few modules providing workarounds for low-level flaws in
|
||||
Django or installed 3rd-party packages.
|
||||
|
||||
locale/
|
||||
Contains translation file for pretix
|
||||
|
||||
multidomain/
|
||||
Additional code implementing our customized :ref:`URL handling <urlconf>`.
|
||||
|
||||
static/
|
||||
Contains all static files (CSS, JavaScript, images)
|
||||
Contains all static files (CSS/SASS, JavaScript, images) of pretix' core
|
||||
We use libsass as a preprocessor for CSS. Our own sass code is built in the same
|
||||
step as Bootstrap and FontAwesome, so their mixins etc. are fully available.
|
||||
|
||||
static/
|
||||
Contains some pretix plugins that ship with pretix itself
|
||||
testutils/
|
||||
Contains helper methods that are useful to write the test suite for pretix or test
|
||||
suites for pretix plugins.
|
||||
|
||||
tests/
|
||||
This is the root directory for all test codes. It includes subdirectories ``base``,
|
||||
``control``, ``presale``, ``helpers`` and ``plugins`` to mirror the structure of the
|
||||
``pretix`` source code as well as ``testdummy``, which is a pretix plugin used during
|
||||
This is the root directory for all test codes. It includes subdirectories ``api``, ``base``,
|
||||
``control``, ``presale``, ``helpers`, ``multidomain`` and ``plugins`` to mirror the structure
|
||||
of the pretix source code as well as ``testdummy``, which is a pretix plugin used during
|
||||
testing.
|
||||
|
||||
Language files
|
||||
--------------
|
||||
|
||||
The language files live in ``pretix/locale/*/LC_MESSAGES/``.
|
||||
|
||||
Static files
|
||||
------------
|
||||
|
||||
Sass source code
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
We use libsass as a preprocessor for CSS. Our own sass code is built in the same
|
||||
step as Bootstrap and FontAwesome, so their mixins etc. are fully available.
|
||||
|
||||
pretix.control
|
||||
pretixcontrol has two main SCSS files, ``pretix/static/pretixcontrol/scss/main.scss`` and
|
||||
``pretix/static/pretixcontrol/scss/auth.scss``, importing everything else.
|
||||
|
||||
pretix.presale
|
||||
pretixpresale has one main SCSS files, ``pretix/pretixpresale/scss/main.scss``,
|
||||
importing everything else.
|
||||
|
||||
3rd-party assets
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
Most client-side 3rd-party assets are vendored in various subdirectories of ``pretix/static``.
|
||||
|
||||
@@ -1,8 +1,6 @@
|
||||
User Guide
|
||||
==========
|
||||
|
||||
Contents:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
|
||||
@@ -1,8 +1,6 @@
|
||||
Accepting payments
|
||||
==================
|
||||
|
||||
Contents:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
|
||||
Reference in New Issue
Block a user