Add public routes feature

docs/development/custom/url-hooks.md

@@ -1,54 +1,65 @@
 # URL Hooks
 
-```eval_rst
-.. note::
-    URLs added through URL Hooks are protected by a decorator which ensures the requesting user is logged in and has a main character set.
-```
+## Base functionality
 
 The URL hooks allow you to dynamically specify URL patterns from your plugin app or service. To achieve this you should subclass or instantiate the `services.hooks.UrlHook` class and then register the URL patterns with the hook.
 
 To register a UrlHook class you would do the following:
 
-    @hooks.register('url_hook')
-    def register_urls():
-        return UrlHook(app_name.urls, 'app_name', r^'app_name/')
+```python
+@hooks.register('url_hook')
+def register_urls():
+    return UrlHook(app_name.urls, 'app_name', r^'app_name/')
+```
 
+### Public views
 
-The `UrlHook` class specifies some parameters/instance variables required for URL pattern inclusion.
+In addition is it possible to make views public. Normally, all views are automatically decorated with the `main_character_required` decorator. That decorator ensures a user needs to be logged in and have a main before he can access that view. This feature protects against a community app sneaking in a public view without the administrator knowing about it.
 
-`UrlHook(urls, app_name, base_url)`
+An app can opt-out of this feature by adding a list of views to be excluded when registering the URLs. See the `excluded_views` parameter for details.
 
-#### urls
-The urls module to include. See [the Django docs](https://docs.djangoproject.com/en/dev/topics/http/urls/#example) for designing urlpatterns.
-#### namespace
-The URL namespace to apply. This is usually just the app name.
-#### base_url
-The URL prefix to match against in regex form. Example `r'^app_name/'`. This prefix will be applied in front of all URL patterns included. It is possible to use the same prefix as existing apps (or no prefix at all) but [standard URL resolution](https://docs.djangoproject.com/en/dev/topics/http/urls/#how-django-processes-a-request) ordering applies (hook URLs are the last ones registered).
+```eval_rst
+.. note::
+    Note that for a public view to work, administrators need to also explicitly allow apps to have public views in their AA installation, by adding the apps label to ``APPS_WITH_PUBLIC_VIEWS`` setting.
+```
 
-### Example
+## Examples
 
 An app called `plugin` provides a single view:
 
-    def index(request):
-        return render(request, 'plugin/index.html')
+```python
+def index(request):
+    return render(request, 'plugin/index.html')
+```
 
 The app's `urls.py` would look like so:
 
-    from django.urls import path
-    import plugin.views
+```python
+from django.urls import path
+import plugin.views
 
-    urlpatterns = [
-        path('index/', plugins.views.index, name='index'),
-    ]
+urlpatterns = [
+    path('index/', plugins.views.index, name='index'),
+]
+```
 
 Subsequently it would implement the UrlHook in a dedicated `auth_hooks.py` file like so:
 
-    from alliance_auth import hooks
-    from services.hooks import UrlHook
-    import plugin.urls
+```python
+from alliance_auth import hooks
+from services.hooks import UrlHook
+import plugin.urls
 
-    @hooks.register('url_hook')
-    def register_urls():
-        return UrlHook(plugin.urls, 'plugin', r^'plugin/')
+@hooks.register('url_hook')
+def register_urls():
+    return UrlHook(plugin.urls, 'plugin', r^'plugin/')
+```
 
 When this app is included in the project's `settings.INSTALLED_APPS` users would access the index view by navigating to `https://example.com/plugin/index`.
+
+## API
+
+```eval_rst
+.. autoclass:: allianceauth.services.hooks.UrlHook
+    :members:
+```