From e437bad1a5cd818fa1c40ad8d4936bade5e92684 Mon Sep 17 00:00:00 2001
From: Matthias Bussonnier <bussonniermatthias@gmail.com>
Date: Wed, 13 Jan 2021 08:09:13 -0800
Subject: [PATCH] DOC: Server extension, extra docs on
 configuration/authentication.

That give most of the information a user needs to write a full-fledge
extension without having to look into tornado documentation:

 - Authentication: I think all handler should be authenticated by
 default.

 - Managing state and accessing server state from the handlers: I don't
 think there is many interesting things you can do without accessing
 server state and configuration.
---
 docs/source/extending/handlers.rst | 47 ++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/docs/source/extending/handlers.rst b/docs/source/extending/handlers.rst
index e853d357d..bc38cdb00 100644
--- a/docs/source/extending/handlers.rst
+++ b/docs/source/extending/handlers.rst
@@ -122,6 +122,53 @@ following:
         route_pattern = url_path_join(web_app.settings['base_url'], '/hello')
         web_app.add_handlers(host_pattern, [(route_pattern, HelloWorldHandler)])
 
+
+Extra Parameters and authentication
+===================================
+
+Here is a quick rundown of what you need to know to pass extra parameters to the handler and enable authentication:
+
+ - extra arguments to the ``__init__`` constructor are given in a dictionary after the  handler class in ``add_handlers``:
+
+.. code:: python
+
+
+    class HelloWorldHandler(IPythonHandler):
+
+        def __init__(self, *args, **kwargs):
+            self.extra = kwargs.pop('extra')
+            ...
+
+    def load_jupyter_server_extension(nb_server_app):
+
+        ...
+
+        web_app.add_handlers(host_pattern,
+            [
+               (route_pattern, HelloWorldHandler, {"extra": nb_server_app.extra})
+            ])
+
+
+All handler methods that require authentication _MUST_ be decorated with ``@tornado.web.authenticated``:
+
+
+.. code:: python
+
+    from tornado import web
+
+    class HelloWorldHandler(IPythonHandler):
+
+        ...
+
+        @web.authenticated
+        def  get(self, *args, **kwargs):
+             ...
+
+        @web.authenticated
+        def  post(self, *args, **kwargs):
+             ...
+
+
 References:
 
 1. `Peter Parente's Mindtrove <https://mindtrove.info/4-ways-to-extend-jupyter-notebook/#nb-server-exts>`__