diff --git a/doc/admin/index.rst b/doc/admin/index.rst index af8e2e4ad..311c345d6 100644 --- a/doc/admin/index.rst +++ b/doc/admin/index.rst @@ -1,10 +1,10 @@ +.. _`admindocs`: + Administrator documentation =========================== This documentation is for everyone who wants to install pretix on a server. -Contents: - .. toctree:: :maxdepth: 2 diff --git a/doc/development/api/index.rst b/doc/development/api/index.rst index e0361f9da..4691c1b0c 100644 --- a/doc/development/api/index.rst +++ b/doc/development/api/index.rst @@ -1,5 +1,5 @@ -Plugin hooks -============ +Plugin development +================== Contents: diff --git a/doc/development/api/plugins.rst b/doc/development/api/plugins.rst index 2bfb5b2b3..6f914468e 100644 --- a/doc/development/api/plugins.rst +++ b/doc/development/api/plugins.rst @@ -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/ diff --git a/doc/development/concepts.rst b/doc/development/concepts.rst index 7bbceabd1..0273bd274 100644 --- a/doc/development/concepts.rst +++ b/doc/development/concepts.rst @@ -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 diff --git a/doc/development/contribution/general.rst b/doc/development/contribution/general.rst index 7b450b676..50024e239 100644 --- a/doc/development/contribution/general.rst +++ b/doc/development/contribution/general.rst @@ -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 --------------- diff --git a/doc/development/contribution/index.rst b/doc/development/contribution/index.rst index a6580bade..7f698eac6 100644 --- a/doc/development/contribution/index.rst +++ b/doc/development/contribution/index.rst @@ -1,5 +1,5 @@ -Contribution guide -================== +Contributing to pretix +====================== .. toctree:: :maxdepth: 2 diff --git a/doc/development/contribution/style.rst b/doc/development/contribution/style.rst index 68f92fd72..20b5c0221 100644 --- a/doc/development/contribution/style.rst +++ b/doc/development/contribution/style.rst @@ -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 `` 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 diff --git a/doc/development/index.rst b/doc/development/index.rst index 1dc86d8f8..ca27b175f 100644 --- a/doc/development/index.rst +++ b/doc/development/index.rst @@ -6,10 +6,10 @@ Developer documentation concepts setup - structure contribution/index implementation/index api/index + structure .. TODO:: Document settings objects, ItemVariation objects, form fields. diff --git a/doc/development/setup.rst b/doc/development/setup.rst index 2a1c407e7..13883387f 100644 --- a/doc/development/setup.rst +++ b/doc/development/setup.rst @@ -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 diff --git a/doc/development/structure.rst b/doc/development/structure.rst index 18dd39b5e..b17d3ba06 100644 --- a/doc/development/structure.rst +++ b/doc/development/structure.rst @@ -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 `. 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``. diff --git a/doc/user/index.rst b/doc/user/index.rst index 2280b8794..d56b4b190 100644 --- a/doc/user/index.rst +++ b/doc/user/index.rst @@ -1,8 +1,6 @@ User Guide ========== -Contents: - .. toctree:: :maxdepth: 2 diff --git a/doc/user/payments/index.rst b/doc/user/payments/index.rst index 6293be4c3..d9b548e57 100644 --- a/doc/user/payments/index.rst +++ b/doc/user/payments/index.rst @@ -1,8 +1,6 @@ Accepting payments ================== -Contents: - .. toctree:: :maxdepth: 2