Merge pull request #82 from TimPushkin/docs

Docs for development tools
TimPushkin · May 16, 2024 · 4ce6f0e · 4ce6f0e
2 parents f8cd508 + db3e8cd
commit 4ce6f0e
Show file tree

Hide file tree

Showing 4 changed files with 83 additions and 31 deletions.
diff --git a/data/map-info-schema.json b/data/map-info-schema.json
@@ -1,20 +1,28 @@
 {
-  "$schema": "http://json-schema.org/draft-04/schema#",
+  "$schema": "https://json-schema.org/draft-07/schema#",
+  "title": "Map description for DepNav",
+  "description": "Provides information on how to visualize a map and its markers in the app",
   "type": "object",
   "properties": {
     "id": {
+      "description": "Identifier of the map, must be unique among identifiers of all other maps available in the app",
       "type": "integer"
     },
     "internalName": {
-      "type": "string"
+      "description": "Name of the map not visible to app's users, it is the one used in assets and resources",
+      "type": "string",
+      "minLength": 1
     },
     "title": {
+      "description": "Name of the map that is visible to app's users",
       "type": "object",
       "properties": {
         "ru": {
+          "description": "Name in Russian",
           "type": "string"
         },
         "en": {
+          "description": "Name in English",
           "type": "string"
         }
       },
@@ -24,31 +32,44 @@
       ]
     },
     "floorWidth": {
-      "type": "integer"
+      "description": "Pixel width of map's floors (on the most detailed zoom level)",
+      "type": "integer",
+      "minimum": 1
     },
     "floorHeight": {
-      "type": "integer"
+      "description": "Pixel height of map's floors (on the most detailed zoom level)",
+      "type": "integer",
+      "minimum": 1
     },
     "tileSize": {
-      "type": "integer"
+      "description": "Pixel size of tiles' sides, e.g. if the tiles are 256x256 this should be 256",
+      "type": "integer",
+      "minimum": 1
     },
     "zoomLevelsNum": {
-      "type": "integer"
+      "description": "Number of zoom levels of map's floors",
+      "type": "integer",
+      "minimum": 1
     },
     "floors": {
+      "description": "Map's floors",
       "type": "array",
       "items": {
         "type": "object",
         "properties": {
           "floor": {
-            "type": "integer"
+            "description": "This floor's number",
+            "type": "integer",
+            "minimum": 1
           },
           "markers": {
+            "description": "Points of interest located on this floor",
             "type": "array",
             "items": {
               "type": "object",
               "properties": {
                 "type": {
+                  "description": "Type of the marker",
                   "type": "string",
                   "enum": [
                     "ENTRANCE",
@@ -64,27 +85,35 @@
                   ]
                 },
                 "x": {
-                  "type": "integer"
+                  "description": "Horizontal pixel coordinate starting from the left",
+                  "type": "integer",
+                  "minimum": 0
                 },
                 "y": {
-                  "type": "integer"
+                  "description": "Vertical pixel coordinate starting from the top",
+                  "type": "integer",
+                  "minimum": 0
                 },
                 "ru": {
+                  "description": "User-visible information about the marker in Russian",
                   "type": "object",
                   "properties": {
                     "title": {
+                      "description": "Name of the marker",
                       "type": [
                         "string",
                         "null"
                       ]
                     },
                     "location": {
+                      "description": "Name of marker's location",
                       "type": [
                         "string",
                         "null"
                       ]
                     },
                     "description": {
+                      "description": "Marker's description",
                       "type": [
                         "string",
                         "null"
@@ -98,21 +127,25 @@
                   ]
                 },
                 "en": {
+                  "description": "User-visible information about the marker in English",
                   "type": "object",
                   "properties": {
                     "title": {
+                      "description": "Name of the marker",
                       "type": [
                         "string",
                         "null"
                       ]
                     },
                     "location": {
+                      "description": "Name of marker's location",
                       "type": [
                         "string",
                         "null"
                       ]
                     },
                     "description": {
+                      "description": "Marker's description",
                       "type": [
                         "string",
                         "null"

diff --git a/tools/README.md b/tools/README.md
@@ -0,0 +1,4 @@
+# Tools
+
+This directory contains various tools that help developing DepNav. Instructions for some of them can
+be found on [DepNav's wiki](https://github.com/TimPushkin/DepNav/wiki).
diff --git a/tools/create_map_db.py b/tools/create_map_db.py
@@ -20,32 +20,44 @@
 from argparse import ArgumentParser
 from enum import Enum
 
-# This script adds the contents of the specified map info json file corresponding to
-# 'map-info-schema.json' into the specified SQLite database.
-# Json is expected to have absolute coordinates, while the database will have them normalized.
-# Coordinates start from top left corner of an image.
-#
-# - Prerequisites: json file corresponding to 'map-info-schema.json'.
-# - Result: database file with the contents of the json file.
-
 
 class LID(Enum):
     EN = 0
     RU = 1
 
 
-parser = ArgumentParser()
-parser.add_argument("json_file", type=pathlib.Path, help="path to the json file")
+parser = ArgumentParser(
+    description="Adds the contents of the specified JSON file (must follow map info schema) into "
+                "the specified SQLite database",
+)
+parser.add_argument(
+    "json",
+    type=pathlib.Path,
+    help="path to the JSON file to read",
+)
+parser.add_argument(
+    "--db",
+    type=pathlib.Path,
+    default="maps.db",
+    help="path to the database to fill, will be created if does not exist",
+)
 parser.add_argument(
-    "-d", "--db_file", type=pathlib.Path, default="maps.db", help="path to the database file"
+    "--db-version",
+    type=int,
+    help="if specified, database version will be set to this value",
 )
 args = parser.parse_args()
+if not args.db.exists() and args.db_version is None:
+    parser.error(
+        f"database file {str(args.db)} does not exist and will be created from scratch — "
+        "a database version must be specified in this case"
+    )
 
-db = sqlite3.connect(str(args.db_file))
+db = sqlite3.connect(str(args.db))
 cur = db.cursor()
 
-db_version = 9  # Database version that this script supports
-cur.execute(f"PRAGMA user_version = {db_version}")
+if args.db_version is not None:
+    cur.execute(f"PRAGMA user_version = {args.db_version}")
 
 cur.executescript(
     """
@@ -126,7 +138,7 @@ class LID(Enum):
     """
 )
 
-m = json.load(open(args.json_file, encoding="utf8"))
+m = json.load(open(args.json, encoding="utf8"))
 
 floor_width = m["floorWidth"]
 floor_height = m["floorHeight"]

diff --git a/tools/transform_markers.py b/tools/transform_markers.py
@@ -24,23 +24,26 @@
 # - Result: the file is changed by applying the transformation.
 
 
-parser = ArgumentParser()
-parser.add_argument("json_file", type=str, help="path to the json file")
+parser = ArgumentParser(
+    description="Applies a linear transformation to marker coordinates in the specified JSON file "
+                "(must follow map info schema)",
+)
+parser.add_argument("json", type=str, help="path to the json file")
 parser.add_argument(
-    "x_multiplier", type=float, help="number on which x coordinate will be multiplied"
+    "x_multiplier", type=float, help="number on which x coordinates will be multiplied"
 )
 parser.add_argument(
-    "y_multiplier", type=float, help="number on which y coordinate will be multiplied"
+    "y_multiplier", type=float, help="number on which y coordinates will be multiplied"
 )
 parser.add_argument(
-    "x_shift", type=int, help="number which will be added to x coordinate"
+    "x_shift", type=int, help="number which will be added to x coordinates"
 )
 parser.add_argument(
-    "y_shift", type=int, help="number which will be added to y coordinate"
+    "y_shift", type=int, help="number which will be added to y coordinates"
 )
 args = parser.parse_args()
 
-with open(args.json_file, "r+", encoding="utf8") as f:
+with open(args.json, "r+", encoding="utf8") as f:
     jf = json.load(f)
 
     for floor_obj in jf["floors"]: