[docs] Added docs

Signed-off-by: DragnEmperor <[email protected]>

Author: DragnEmperor

docs/index.rst

@@ -49,6 +49,7 @@ the OpenWISP architecture.
     user/openvpn.rst
     user/subnet-division-rules.rst
     user/whois.rst
+    user/approximate-location.rst
     user/rest-api.rst
     user/settings.rst
 

docs/user/approximate-location.rst

@@ -0,0 +1,47 @@
+Approximate Location
+====================
+
+.. important::
+
+    The **Approximate Location** feature is **disabled by default**.
+
+    Before enabling it, the :doc:`WHOIS Lookup feature <whois>` must be
+    enabled and then set
+    :ref:`OPENWISP_CONTROLLER_APPROXIMATE_LOCATION_ENABLED` to ``True``
+
+.. contents:: **Table of contents**:
+    :depth: 1
+    :local:
+
+Overview
+--------
+
+The Approximate Location feature automatically creates or updates a
+device’s location based on latitude and longitude information retrieved
+from the WHOIS Lookup feature.
+
+Trigger Conditions
+------------------
+
+Approximate Location is triggered when:
+
+- A **fresh WHOIS lookup** is performed for a device.
+- Or when a WHOIS record already exists for the device’s IP **and**:
+
+  - The device’s last IP address is **public**.
+  - WHOIS lookup and Approximate Location is **enabled** for the device’s
+    organization.
+
+Behavior
+--------
+
+If **a matching location already exists** for another device with the same
+IP, the system will **attach that location** to the current device if:
+
+- Only one device is found with that IP and it has a location.
+- The current device **has no location** or if it does then the location
+  is **approximate**.
+
+If there is **no matching location**, a new approximate location is
+created or the existing one is updated using coordinates from the WHOIS
+record, but only if the existing location is approximate.

docs/user/settings.rst

@@ -795,3 +795,20 @@ Maxmind Account ID required for the :doc:`WHOIS Lookup feature <whois>`.
 ============ =======
 
 Maxmind License Key required for the :doc:`WHOIS Lookup feature <whois>`.
+
+.. _openwisp_controller_whois_approximate_location_enabled:
+
+``OPENWISP_CONTROLLER_WHOIS_APPROXIMATE_LOCATION_ENABLED``
+----------------------------------------------------------
+
+============ =========
+**type**:    ``bool``
+**default**: ``False``
+============ =========
+
+Allows enabling the optional :doc:`Approximate Location feature
+<approximate-location>`.
+
+.. image:: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/1.3/approximate-location-setting.png
+    :target: https://raw.githubusercontent.com/openwisp/openwisp-controller/docs/docs/1.3/approximate-location-setting.png
+    :alt: Approximate Location setting

openwisp_controller/config/admin.py

@@ -1384,7 +1384,7 @@ def get_fields(self, request, obj=None):
         if app_settings.REGISTRATION_ENABLED:
             fields += ["registration_enabled", "shared_secret"]
         if app_settings.WHOIS_CONFIGURED:
-            fields += ["whois_enabled"]
+            fields += ["whois_enabled", "approximate_location_enabled"]
         fields += ["context"]
         return fields
 

openwisp_controller/config/whois/test_whois.py

@@ -19,7 +19,6 @@
 from utils import WHOISTransactionMixin
 
 Device = load_model("config", "Device")
-Location = load_model("geo", "Location")
 WHOISInfo = load_model("config", "WHOISInfo")
 Notification = load_model("openwisp_notifications", "Notification")
 OrganizationConfigSettings = load_model("config", "OrganizationConfigSettings")

openwisp_controller/geo/approximate_location/tasks.py

@@ -10,8 +10,8 @@
 @shared_task
 def manage_approximate_locations(device_pk, ip_address, add_existing=False):
     """
-    Creates/updates fuzzy location for a device based on the latitude and longitude
-    or attaches an existing location if `add_existing` is True.
+    Creates/updates approximate location for a device based on the latitude and
+    longitude or attaches an existing location if `add_existing` is True.
     Existing location here means a location of another device whose last_ip matches
     the given ip_address.
 
@@ -21,7 +21,7 @@ def manage_approximate_locations(device_pk, ip_address, add_existing=False):
 
     When `add_existing` is False:
     - A new location is created if no location exists for current device, or
-    existing one is updated using coords from WHOIS record if it is approximate(fuzzy).
+    existing one is updated using coords from WHOIS record if it is approximate (fuzzy).
     """
     from openwisp_controller.config.whois.utils import send_whois_task_notification
 
@@ -41,9 +41,9 @@ def _create_update_location():
         coords = Point(whois_obj.longitude, whois_obj.latitude, srid=4326)
         address = whois_obj.formatted_address
         location_name = (
-            " ".join(address.split(",")[:2])
+            ",".join(address.split(",")[:2]) + f" (Estimated: {ip_address})"
             if address
-            else f"Approximate Location {ip_address}"
+            else f"Estimated Location: {ip_address}"
         )
         # Used to update an existing location if it is approximate
         # or create a new one if it doesn't exist
@@ -100,5 +100,5 @@ def _create_update_location():
         _create_update_location()
 
     logger.info(
-        f"Fuzzy location saved successfully for {device_pk} for IP: {ip_address}"
+        f"Approximate location saved successfully for {device_pk} for IP: {ip_address}"
     )

openwisp_controller/geo/approximate_location/test_approximate_location.py

@@ -4,6 +4,7 @@
 from django.contrib.gis.geos import GEOSGeometry
 from django.core.exceptions import ImproperlyConfigured, ValidationError
 from django.test import TestCase, TransactionTestCase, override_settings
+from django.urls import reverse
 from swapper import load_model
 
 from openwisp_controller.config import settings as config_app_settings
@@ -60,6 +61,41 @@ def test_approximate_location_configuration_setting(self):
             except AssertionError:
                 self.fail("ValidationError message not equal to expected message.")
 
+        with self.subTest(
+            "Test Approximate Location field visible on admin when "
+            "WHOIS_CONFIGURED True"
+        ):
+            self._login()
+            org = self._get_org()
+            url = reverse(
+                "admin:openwisp_users_organization_change",
+                args=[org.pk],
+            )
+            response = self.client.get(url)
+            self.assertContains(
+                response, 'name="config_settings-0-approximate_location_enabled"'
+            )
+
+        with override_settings(
+            OPENWISP_CONTROLLER_WHOIS_GEOIP_ACCOUNT=None,
+            OPENWISP_CONTROLLER_WHOIS_GEOIP_KEY=None,
+        ):
+            importlib.reload(config_app_settings)
+            with self.subTest(
+                "Test Approximate Location field hidden on admin when "
+                "WHOIS_CONFIGURED False"
+            ):
+                self._login()
+                org = self._get_org()
+                url = reverse(
+                    "admin:openwisp_users_organization_change",
+                    args=[org.pk],
+                )
+                response = self.client.get(url)
+                self.assertNotContains(
+                    response, 'name="config_settings-0-approximate_location_enabled"'
+                )
+
 
 class TestApproximateLocationTransaction(
     TestApproximateLocationMixin, WHOISTransactionMixin, TransactionTestCase
@@ -128,7 +164,7 @@ def _verify_location_details(device, mocked_response):
         mocked_response = self._mocked_client_response()
         mock_client.return_value.city.return_value = mocked_response
 
-        with self.subTest("Test Fuzzy location created when device is created"):
+        with self.subTest("Test Approximate location created when device is created"):
             device = self._create_device(last_ip="172.217.22.14")
 
             location = device.devicelocation.location
@@ -137,7 +173,7 @@ def _verify_location_details(device, mocked_response):
             self.assertEqual(location.type, "outdoor")
             _verify_location_details(device, mocked_response)
 
-        with self.subTest("Test Fuzzy location updated when last ip is updated"):
+        with self.subTest("Test Approximate location updated when last ip is updated"):
             device.last_ip = "172.217.22.10"
             mocked_response.location.latitude = 50
             mocked_response.location.longitude = 150