Update write-metrics-md.py with comments

Author: jukent

.github/workflows/write-metrics-md.py

@@ -2,6 +2,9 @@
 
 
 def process_user_data(json_file, top_pages, this_year, map, md_file):
+    """
+    Function for writing portal/metrics.md from saved files output by get-metrics.py
+    """
     with open(json_file, 'r') as f:
         user_data = json.load(f)
 
@@ -12,6 +15,7 @@ def process_user_data(json_file, top_pages, this_year, map, md_file):
         user_data.pop('Now')
         f.write('\n\n')
 
+        # Markdown table
         headers = '| Project | Users |'
         separator = '| ' + ' | '.join(['-----'] * 2) + ' |'
         rows = []
@@ -21,6 +25,7 @@ def process_user_data(json_file, top_pages, this_year, map, md_file):
         f.write(table)
         f.write('\n\n')
 
+        # Add plots
         f.write(f'![Users this Year]({this_year})\n\n')
         f.write(f'![Top Pages]({top_pages})\n\n')
         f.write(f'![Users by Country]({map})\n\n')
@@ -29,9 +34,12 @@ def process_user_data(json_file, top_pages, this_year, map, md_file):
 
 
 if __name__ == '__main__':
-    json_file = 'portal/metrics/user_metrics.json'
+    json_file = 'portal/metrics/user_metrics.json'  # Accessed from root repository
+
+    # HTML is built from within `portal/` directory, so paths differ from json file.
     top_pages = 'metrics/toppages.png'
     this_year = 'metrics/thisyear.png'
     map = 'metrics/bycountry.png'
-    md_file = 'portal/metrics.md'
+
+    md_file = 'portal/metrics.md'  # Written from root repository
     process_user_data(json_file, top_pages, this_year, map, md_file)