1 files changed, 72 insertions, 0 deletions
diff --git a/toolkit/modules/docs/Region.rst b/toolkit/modules/docs/Region.rst
new file mode 100644
index 0000000000..1e95739f4a
--- /dev/null
+++ b/toolkit/modules/docs/Region.rst
@@ -0,0 +1,72 @@
+.. _Region:
+
+======
+Region
+======
+
+Firefox monitors the users region in order to show relevant local
+search engines and content. The region is tracked in 2 properties:
+
+ * ``Region.current`` - The most recent location we detected for the user.
+ * ``Region.home`` - Where we consider the users home location.
+
+These are tracked separately as to avoid updating the users
+experience repeatedly as they travel for example. In general
+callers should use ``Region.home``.
+
+If the user is detected in a current region that is not there `home` region
+for a continuous period (current 2 weeks) then their `home` region
+will be updated.
+
+Testing
+=======
+
+To set the users region for testing you can use ``Region._setHomeRegion("US", false)``, the second parameter ``notify``
+will send a notification that the region has changed and trigger a
+reload of search engines and other content.
+
+Updating test_Region_geocoding.js data
+--------------------------------------
+
+The test data used in this test is generated by running the MLS geocoding
+service locally:
+
+Follow the Ichnaea location development guide @ https://ichnaea.readthedocs.io/en/latest/local_dev.html.
+
+Make a list of test locations in a CSV format, for example:
+
+.. code-block:: shell
+
+  23.7818724,38.0531587
+  23.7728138,38.0572369
+  1.6780180,48.5973431
+  1.7034801,48.5979913
+  1.6978640,48.5919751
+
+You can use the MLS raw data files to get a large sample @ https://location.services.mozilla.com/downloads
+
+Save a script to run the geocoding in ``ichnaea/ichnaea``
+
+.. code-block:: python
+
+  import geocode
+  geocoder = geocode.Geocoder()
+
+  f = open("mls.csv", "r")
+  r = open("mls-lookup-results.csv", "a")
+
+  for x in f:
+    [lat, long] = x.strip().split(",")
+    region = geocoder.region(lat, long)
+    r.write("%s\n" % region)
+
+Run the script
+
+.. code-block:: shell
+
+  $ make shell
+  $ cd ichnaea
+  $ python run.py
+
+If you want to commit the new test data ~500 seems to be a reasonable
+number of data points to test before running into issues with the test length.