Docs: Update implementation docs for URL routing (#3510)

doc/development/implementation/urlconfig.rst

@@ -15,25 +15,33 @@ and the admin panel is available at ``https://pretix.eu/control/event/bigorg/awe
 
 If the organizer now configures a custom domain like ``tickets.bigorg.com``, his event will
 from now on be available on ``https://tickets.bigorg.com/awesomecon/``. The former URL at
-``pretix.eu`` will redirect there. However, the admin panel will still only be available
-on ``pretix.eu`` for convenience and security reasons.
+``pretix.eu`` will redirect there. It's also possible to do this for just an event, in which
+case the event will be available on ``https://tickets.awesomecon.org/``.
+
+However, the admin panel will still only be available on ``pretix.eu`` for convenience and security reasons.
 
 URL routing
 -----------
 
 The hard part about implementing this URL routing in Django is that
 ``https://pretix.eu/bigorg/awesomecon/`` contains two parameters of nearly arbitrary content
-and ``https://tickets.bigorg.com/awesomecon/`` contains only one. The only robust way to do
-this is by having *separate* URL configuration for those two cases. In pretix, we call the
-former our ``maindomain`` config and the latter our ``subdomain`` config. For pretix's core
-modules we do some magic to avoid duplicate configuration, but for a fairly simple plugin with
-only a handful of routes, we recommend just configuring the two URL sets separately.
+and ``https://tickets.bigorg.com/awesomecon/`` contains only one and ``https://tickets.awesomecon.org/`` does not contain any.
+The only robust way to do this is by having *separate* URL configuration for those three cases.
 
+In pretix, we therefore do not have a global URL configuration, but three, living in the following modules:
+
+- ``pretix.multidomain.maindomain_urlconf``
+- ``pretix.multidomain.organizer_domain_urlconf``
+- ``pretix.multidomain.event_domain_urlconf``
+
+We provide some helper utilities to work with these to avoid duplicate configuration of the individual URLs.
 The file ``urls.py`` inside your plugin package will be loaded and scanned for URL configuration
 automatically and should be provided by any plugin that provides any view.
+However, unlike plain Django, we look not only for a ``urlpatterns`` attribute on the module but support other
+attributes like ``event_patterns`` and ``organizer_patterns`` as well.
 
-A very basic example that provides one view in the admin panel and one view in the frontend
-could look like this::
+For example, for a simple plugin that adds one URL to the backend and one event-level URL to the frontend, you can
+create the following configuration in your ``urls.py``::
 
     from django.urls import re_path
 
@@ -52,7 +60,7 @@ could look like this::
     As you can see, the view in the frontend is not included in the standard Django ``urlpatterns``
     setting but in a separate list with the name ``event_patterns``. This will automatically prepend
     the appropriate parameters to the regex (e.g. the event or the event and the organizer, depending
-    on the called domain).
+    on the called domain). For organizer-level views, ``organizer_patterns`` works the same way.
 
 If you only provide URLs in the admin area, you do not need to provide a ``event_patterns`` attribute.
 
@@ -71,11 +79,16 @@ is a python method that emulates a behavior similar to ``reverse``:
 
 .. autofunction:: pretix.multidomain.urlreverse.eventreverse
 
+If you need to communicate the URL externally, you can use a different method to ensure that it is always an absolute URL:
+
+.. autofunction:: pretix.multidomain.urlreverse.build_absolute_uri
+
 In addition, there is a template tag that works similar to ``url`` but takes an event or organizer object
 as its first argument and can be used like this::
 
     {% load eventurl %}
     <a href="{% eventurl request.event "presale:event.checkout" step="payment" %}">Pay</a>
+    <a href="{% abseventurl request.event "presale:event.checkout" step="payment" %}">Pay</a>
 
 
 Implementation details

src/pretix/multidomain/urlreverse.py

@@ -128,7 +128,7 @@ def eventreverse(obj, name, kwargs=None):
     :param kwargs: A dictionary of additional keyword arguments that should be used. You do not
         need to provide the organizer or event slug here, it will be added automatically as
         needed.
-    :returns: An absolute URL (including scheme and host) as a string
+    :returns: An absolute or relative URL as a string
     """
     from pretix.multidomain import (
         event_domain_urlconf, maindomain_urlconf, organizer_domain_urlconf,
@@ -177,6 +177,17 @@ def eventreverse(obj, name, kwargs=None):
 
 
 def build_absolute_uri(obj, urlname, kwargs=None):
+    """
+    Works similar to ``eventreverse`` but always returns an absolute URL.
+
+    :param obj: An ``Event`` or ``Organizer`` object
+    :param name: The name of the URL route
+    :type name: str
+    :param kwargs: A dictionary of additional keyword arguments that should be used. You do not
+        need to provide the organizer or event slug here, it will be added automatically as
+        needed.
+    :returns: An absolute URL (including scheme and host) as a string
+    """
     reversedurl = eventreverse(obj, urlname, kwargs)
     if '://' in reversedurl:
         return reversedurl