CGM_Public/pretix_cgo
1
0
Fork 0
forked from CGM_Public/pretix_original
Code Pull Requests Actions Activity

Various docs improvements

Browse Source
This commit is contained in:
Raphael Michel
2017-06-19 12:01:00 +02:00
parent b2d4bea1d0
commit 4b12678fa4
12 changed files with 118 additions and 125 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
doc/admin/index.rst
View File

@@ -1,10 +1,10 @@
.. _`admindocs`:
Administrator documentation Administrator documentation
=========================== ===========================
This documentation is for everyone who wants to install pretix on a server. This documentation is for everyone who wants to install pretix on a server.
Contents:
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2

4
doc/development/api/index.rst
View File

@@ -1,5 +1,5 @@
Plugin hooks Plugin development
============ ==================
Contents: Contents:

60
doc/development/api/plugins.rst
View File

@@ -1,8 +1,10 @@
.. highlight:: python .. highlight:: python
:linenothreshold: 5 :linenothreshold: 5
Plugin basics .. _`pluginsetup`:
=============
Creating a plugin
=================
It is possible to extend pretix with custom Python code using the official 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 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 ``pretix.control`` and ``pretix.presale`` expose a number of signals which are documented
on the next pages. on the next pages.
.. _`pluginsetup`:
To create a new plugin, create a new python package which must be a valid `Django app`_ 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. 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 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, 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 The plugin metadata lives inside a ``PretixPluginMeta`` class inside your app's
configuration class. The metadata class must define the following attributes: configuration class. The metadata class must define the following attributes:
``name`` (``str``): .. rst-class:: rest-resource-table
The human-readable name of your plugin
``author`` (``str``): ================== ==================== ===========================================================
Your name Attribute Type Description
================== ==================== ===========================================================
``version`` (``str``): name string The human-readable name of your plugin
A human-readable version code of your plugin author string Your name
version string A human-readable version code of your plugin
``description`` (``str``): description string A more verbose description of what your plugin does.
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
``visible`` (``bool``): for an event by system administrators / superusers.
``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.
A working example would be:: A working example would be::
# file: pretix/plugins/timerestriction/__init__.py
from django.apps import AppConfig from django.apps import AppConfig
from django.utils.translation import ugettext_lazy as _ from django.utils.translation import ugettext_lazy as _
class PaypalApp(AppConfig): class PaypalApp(AppConfig):
name = 'pretix.plugins.paypal' name = 'pretix_paypal'
verbose_name = _("Stripe") verbose_name = _("PayPal")
class PretixPluginMeta: class PretixPluginMeta:
name = _("PayPal") name = _("PayPal")
@@ -69,8 +70,7 @@ A working example would be::
description = _("This plugin allows you to receive payments via PayPal") 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 The ``AppConfig`` class may implement a property ``compatiblity_errors``, that checks
whether the pretix installation meets all requirements of the plugin. If so, 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:: in a separate python package, your ``setup.py`` should contain something like this::
setup( setup(
… args...,
entry_points=""" entry_points="""
[pretix.plugin] [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 of your plugin. You should extend your ``AppConfig`` (see above) by the following
method to make your receivers available:: method to make your receivers available::
class TimeRestrictionApp(AppConfig): class PaypalApp(AppConfig):
… …
def ready(self): def ready(self):
@@ -131,3 +130,4 @@ your Django app label.
.. _signal dispatcher: https://docs.djangoproject.com/en/1.7/topics/signals/ .. _signal dispatcher: https://docs.djangoproject.com/en/1.7/topics/signals/
.. _namespace packages: http://legacy.python.org/dev/peps/pep-0420/ .. _namespace packages: http://legacy.python.org/dev/peps/pep-0420/
.. _entry point: https://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins .. _entry point: https://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins
.. _cookiecutter: https://cookiecutter.readthedocs.io/en/latest/

21
doc/development/concepts.rst
View File

@@ -1,18 +1,16 @@
Implementation concepts Concepts and Terminology
======================= ========================
Basic terminology
-----------------
The components 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** **base**
This is the foundation below all other components. It is primarily This is the foundation below all other components. It is primarily
responsible for the data structures and database communication. It also hosts 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** **control**
This is the web-based backend software which allows organizers to 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** **presale**
This is the ticket-shop itself, containing all of the parts visible to the 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 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 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 non-expired items currently in the shopping cart of users
* The number of vouchers defined as "quota blocking" (see blow) * 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 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 your limit is never exceeded. For example, when the payment period of an order expires without the order being

3
doc/development/contribution/general.rst
View File

@@ -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. 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! 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 Sending a patch
--------------- ---------------

4
doc/development/contribution/index.rst
View File

@@ -1,5 +1,5 @@
Contribution guide Contributing to pretix
================== ======================
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2

49
doc/development/contribution/style.rst
View File

@@ -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 * For templates and models, please take a look at the `Django Coding Style`_. We like Django's `class-based views`_ and
with a default configuration for flake8 that excludes migrations and other non-relevant kindly ask you to use them where appropriate.
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.
* 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 * We expect all new code to come with proper tests. When writing new tests, please write them using `pytest-style`_
* F403: ``from module import *`` used; unable to detect undefined names test functions and raw ``assert`` statements. Use `fixtures`_ to prevent repetitive code. Some old parts of pretix'
* F401: module imported but unused test suite are in the style of Python's unit test module. If you extend those files, you might continue in this style,
* N802: function names should be lowercase but please use pytest style for any new test files.
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.
.. _PEP 8: http://legacy.python.org/dev/peps/pep-0008/ .. _PEP 8: http://legacy.python.org/dev/peps/pep-0008/
.. _flake8: https://pypi.python.org/pypi/flake8 .. _flake8: https://pypi.python.org/pypi/flake8
.. _Django Coding Style: https://docs.djangoproject.com/en/dev/internals/contributing/writing-code/coding-style/ .. _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

2
doc/development/index.rst
View File

@@ -6,10 +6,10 @@ Developer documentation
concepts concepts
setup setup
structure
contribution/index contribution/index
implementation/index implementation/index
api/index api/index
structure
.. TODO:: .. TODO::
Document settings objects, ItemVariation objects, form fields. Document settings objects, ItemVariation objects, form fields.

34
doc/development/setup.rst
View File

@@ -1,7 +1,11 @@
.. _`devsetup`: .. _`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 Obtain a copy of the source code
-------------------------------- --------------------------------
@@ -12,6 +16,8 @@ You can just clone our git repository::
External Dependencies External Dependencies
--------------------- ---------------------
Your should install the following on your system:
* Python 3.4 or newer * Python 3.4 or newer
* ``pip`` for Python 3 (Debian package: ``python3-pip``) * ``pip`` for Python 3 (Debian package: ``python3-pip``)
* ``pyvenv`` for Python 3 (Debian package: ``python3-venv``) * ``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/ cd src/
pip3 install -r requirements.txt -r requirements/dev.txt 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 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 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 . flake8 .
isort -c -rc . isort -c -rc .
python manage.py check python manage.py check
Execute the following command to run pretix' test suite (might take a coumple of minutes)::
py.test py.test
.. note:: If you have multiple CPU cores and want to speed up the test suite, you can install the python .. 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 #!/bin/sh
cd $GIT_DIR/../src cd $GIT_DIR/../src
source ../env/bin/activate flake8 . || exit 1
flake8 --ignore=E123,E128,F403,F401,N802,W503 . isort -q -rc -c . || exit 1
This keeps you from accidentally creating commits violating the sdtyle guide.
Working with mails Working with mails
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^
@@ -151,8 +165,14 @@ To build the documentation, run the following command from the ``doc/`` director
make html 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 .. _Django's documentation: https://docs.djangoproject.com/en/1.11/ref/django-admin/#runserver
.. _pretixdroid: https://github.com/pretix/pretixdroid .. _pretixdroid: https://github.com/pretix/pretixdroid

58
doc/development/structure.rst
View File

@@ -1,13 +1,10 @@
Project structure Directory structure
================= ===================
Python source code
------------------
All the source code lives in ``src/``, which has several subdirectories. All the source code lives in ``src/``, which has several subdirectories.
pretix/ pretix/
This directory contains nearly all source code. This directory contains nearly all source code that belongs to pretix.
base/ base/
This is the Django app containing all the models and methods which are This is the Django app containing all the models and methods which are
@@ -19,48 +16,31 @@ pretix/
presale/ presale/
This is the Django app containing the front end for users buying tickets. 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/
Helpers contain a very few modules providing workarounds for low-level flaws in Helpers contain a very few modules providing workarounds for low-level flaws in
Django or installed 3rd-party packages. Django or installed 3rd-party packages.
locale/
Contains translation file for pretix
multidomain/ multidomain/
Additional code implementing our customized :ref:`URL handling <urlconf>`. Additional code implementing our customized :ref:`URL handling <urlconf>`.
static/ 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/ testutils/
Contains some pretix plugins that ship with pretix itself Contains helper methods that are useful to write the test suite for pretix or test
suites for pretix plugins.
tests/ tests/
This is the root directory for all test codes. It includes subdirectories ``base``, This is the root directory for all test codes. It includes subdirectories ``api``, ``base``,
``control``, ``presale``, ``helpers`` and ``plugins`` to mirror the structure of the ``control``, ``presale``, ``helpers`, ``multidomain`` and ``plugins`` to mirror the structure
``pretix`` source code as well as ``testdummy``, which is a pretix plugin used during of the pretix source code as well as ``testdummy``, which is a pretix plugin used during
testing. 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``.

2
doc/user/index.rst
View File

@@ -1,8 +1,6 @@
User Guide User Guide
========== ==========
Contents:
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2

2
doc/user/payments/index.rst
View File

@@ -1,8 +1,6 @@
Accepting payments Accepting payments
================== ==================
Contents:
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2