From c83b90ddc90966ce7d315497be6810fcac40e9b2 Mon Sep 17 00:00:00 2001
From: xtrinch <mojca.rojko@gmail.com>
Date: Thu, 16 Dec 2021 10:28:31 +0100
Subject: [PATCH] Update read the docs

---
 docs/index.rst | 51 +++++++++++++++++++++++++++++++++++---------------
 1 file changed, 36 insertions(+), 15 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index 7f1b9655..87ba27f7 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -36,15 +36,15 @@ Migration to v1.0
 
 We've replaced Python package ``pyfcm`` for Firebase's own package ``firebase-admin``.
 Thus, we no longer use an API key. Instead, you'll need an environment variable
-``GOOGLE_APPLICATION_CREDENTIALS`` which is a path pointing to your JSON credentials.
-To learn more, visit the
-`Google Cloud docs <https://cloud.google.com/docs/authentication/getting-started>`_
+``GOOGLE_APPLICATION_CREDENTIALS`` which is a path pointing to your JSON-file stored
+credentials. To learn more or view other options to input credentials, visit the
+`Google Cloud docs <https://cloud.google.com/docs/authentication/getting-started>`_.
 
 Finally, in your ``settings.py`` (or whatever imported file), add:
 
 .. code-block:: python
 
-    from firebase_admin import firebase_init
+    from firebase_admin import initialize_app
     FIREBASE_APP = initialize_app()
     # Or just
     initialize_app()
@@ -55,11 +55,11 @@ methods. Instead, everything is under a single method: ``send_message``
 
 .. code-block:: python
 
-    from fcm_django.messaging import Message, Notification
-    FCMDevice.objects.send_message(Message(data=dict())
-    # A title, body, and image kwargs are under Notification
+    from firebase_admin.messaging import Message, Notification
+    FCMDevice.objects.send_message(Message(data=dict()))
+    # Note: You can also combine the data and notification kwarg
     FCMDevice.objects.send_message(
-        Message(notification=Notification(title="title", body="body", image="image_url")
+        Message(notification=Notification(title="title", body="body", image="image_url"))
     )
     device = FCMDevice.objects.first()
     device.send_message(Message(...))
@@ -69,14 +69,15 @@ of bulk messages.
 
 .. code-block:: python
 
-    from fcm_django.messaging import Message, Notification
-    FCMDevice.objects.handle_subscription(True, "A topic")
-    message = Message(..., topic="A Topic")
+    from firebase_admin.messaging import Message, Notification
+    topic = "A topic"
+    FCMDevice.objects.handle_subscription(True, topic)
+    message = Message(..., topic=topic)
     FCMDevice.objects.filter(is_cool=True).send_message(message)
 
 There are two additional parameters to both methods:
 ``skip_registration_id_lookup`` and ``additional_registration_ids``.
-Visit ``Sending Messages`` to learn more.
+Visit `Sending Messages <https://github.com/xtrinch/fcm-django#sending-messages>`_ to learn more.
 
 Note: ``registration_ids`` is actually incorrect terminology as it
 should actually be called ``registration tokens``. However, to be
@@ -88,7 +89,9 @@ Setup
 -----
 You can install the library directly from pypi using pip:
 
-    $ pip install fcm-django
+.. code-block::
+
+    pip install fcm-django
 
 
 Edit your settings.py file:
@@ -123,6 +126,10 @@ Edit your settings.py file:
          # are deleted upon receiving error response from FCM
          # default: False
         "DELETE_INACTIVE_DEVICES": True/False,
+        # Transform create of an existing Device (based on registration id) into
+		    # an update. See the section
+        # "Update of device with duplicate registration ID" for more details.
+        "UPDATE_ON_DUPLICATE_REG_ID": True/False,
     }
 
 Native Django migrations are in use. ``manage.py migrate`` will install and migrate all models.
@@ -246,7 +253,7 @@ lookup that goes along with your query.
 
     from firebase_admin.messaging import Message
     from fcm_django.models import FCMDevice
-    FCMDevice.objects.send_message(Message(...), ["registration_ids"], False)
+    FCMDevice.objects.send_message(Message(...), False, ["registration_ids"])
 
 Using multiple FCM apps
 -----------------------
@@ -264,6 +271,7 @@ By default the message will be sent using the default FCM ``firebase_admin.App``
 
 Django REST Framework (DRF) support
 -----------------------------------
+
 Viewsets come in two different varieties:
 
 - ``FCMDeviceViewSet``
@@ -315,6 +323,18 @@ Routes can be added one of two ways:
         # ...
     ]
 
+Update of device with duplicate registration ID
+-----------------------------------------------
+
+The DRF viewset enforce the uniqueness of the registration ID. In same use case it
+may cause an issue: If an already registered mobile device changes its user, then
+it will fail to register because the registration ID already exist.
+
+When option ``UPDATE_ON_DUPLICATE_REG_ID`` is set to True, then any creation of
+device with an already existing registration ID will be transformed into an update.
+
+The ``UPDATE_ON_DUPLICATE_REG_ID`` only works with DRF.
+
 Python 3 support
 ----------------
 ``fcm-django`` is fully compatible with Python 3.6+
@@ -337,4 +357,5 @@ Submit an issue/PR on this project. Please do not send me emails, as then the co
 Contributing
 ------------
 
-To setup the development environment, simply do `pip install -r requirements.txt`
+To setup the development environment, simply do ``pip install -r requirements.txt``
+To manually run the pre-commit hook, run `pre-commit run --all-files`.