Update notes on adding a route

Author: nickswalker

README.md

@@ -74,7 +74,13 @@ Both plans and individual legs can include a `cancelled` key:
 
 ### Adding a Route
 
-To add a new route, add a GPX file to the `routes/_gpx/` directory. Route files follow strict formatting rules, which get checked by `_bin/make_routes_table.py`. The build will fail with a descriptive error if any route doesn't meet the minimum formatting requirements.
+Add a GPX file to the `routes/_gpx/` directory. The build will fail with a descriptive error if any route doesn't meet the minimum formatting requirements which get checked by `_bin/make_routes_table.py`. 
+  
+  * The file's `<gpx>` tag must include the RCR extension: `<gpx xmlns="http://www.topografix.com/GPX/1/1" version="1.1" creator="Race Condition Running" xmlns:rcr="http://raceconditionrunning.com/extensions">`
+  * `<name>` - lowercase, hyphenated name of the route. Ends with `loop` if the route is a loop or `ob` if the route is an out-and-back.
+  * `<desc>` - The presentation name of the route, e.g. "Lake Union Loop".
+  * You must include an `<extensions>` tag in the `<metadata>` section, with
+    `<rcr:last_updated>YYYY-MM-DD</rcr:last_updated>`.
 
 Before you commit changes to a route, run `make normalize-routes-in-place` to ensure the route is formatted correctly.
 

_bin/rcr.py

@@ -67,7 +67,7 @@ def load_route(path):
             with open(path, 'r') as f:
                 reader = gpxpy.parse(f)
         except Exception as e:
-            raise GPXParseError(f"Could not parse '{path}'\n{e}")
+            raise GPXParseError(f"Could not parse '{path}'\n{e}. Make sure rcr extension is specified.")
 
         # Recursively strip `{<extension_url}:` prefix from metadata keys. Nesting only used for changelog right now
         def strip_rcr_prefix(item_list):
@@ -98,6 +98,14 @@ def strip_rcr_prefix(item_list):
         if not track:
             raise GPXFormatError(f"Bogus number of tracks in:\n{path}")
 
+        if not track.description:
+            raise GPXFormatError(f"Track description (<desc>) is empty in:\n{path}")
+        extracted_distance = None
+        try:
+            extracted_distance = float(track.description.split("(")[1].split("mi)")[0].strip())
+        except (ValueError, IndexError):
+            raise GPXFormatError(f"Could not extract distance from track description in:\n{path}. Should be in format 'Description (X mi)'")
+
         ascent = metadata.get('ascent', None)
         if ascent:
             ascent = float(ascent)
@@ -115,7 +123,7 @@ def strip_rcr_prefix(item_list):
             'id': path.stem,
             'name': metadata.get('name', track.description.split("(")[0].strip()),
             'last_updated': metadata.get('last_updated', None),
-            'distance_mi': metadata.get('distance', float(track.description.split("(")[1].split("mi)")[0].strip())),
+            'distance_mi': metadata.get('distance', extracted_distance),
             'ascent_m': ascent,
             'descent_m': descent,
             'map': metadata.get('map', None),