Allow generate-spec to take optional output file

.github/workflows/tests.yml

@@ -141,7 +141,7 @@ jobs:
         pip install file://$PWD#egg=ipywidgets
     - name: Compare spec with latest version
       run: |
-        python ./packages/schema/generate-spec.py -f markdown > spec.md
+        python ./packages/schema/generate-spec.py -f markdown spec.md
         diff -u ./packages/schema/jupyterwidgetmodels.latest.md ./spec.md
   ui-test:
     name: Visual Regression

docs/source/dev_install.md

@@ -75,8 +75,8 @@ Updating widget model specification
 
 To update the widget model specification with changes, do something like this in the repo root:
 ```
-python ./packages/schema/generate-spec.py -f json-pretty > packages/schema/jupyterwidgetmodels.latest.json
-python ./packages/schema/generate-spec.py -f markdown > packages/schema/jupyterwidgetmodels.latest.md
+python ./packages/schema/generate-spec.py -f json-pretty packages/schema/jupyterwidgetmodels.latest.json
+python ./packages/schema/generate-spec.py -f markdown packages/schema/jupyterwidgetmodels.latest.md
 ```
 
 Releasing new versions

docs/source/dev_release.md

@@ -28,8 +28,8 @@ First, update the relevant model specification versions. For example, the commit
 
 Next, regenerate the model spec with the new version numbers by doing something like this in the repository root directory:
 ```
-python ./packages/schema/generate-spec.py -f json-pretty > packages/schema/jupyterwidgetmodels.latest.json
-python ./packages/schema/generate-spec.py -f markdown > packages/schema/jupyterwidgetmodels.latest.md
+python ./packages/schema/generate-spec.py -f json-pretty packages/schema/jupyterwidgetmodels.latest.json
+python ./packages/schema/generate-spec.py -f markdown packages/schema/jupyterwidgetmodels.latest.md
 ```
 
 Copy `packages/schema/jupyterwidgetmodels.latest.md` to an appropriately-named

packages/schema/generate-spec.py

@@ -4,6 +4,8 @@
 import argparse
 import json
 from operator import itemgetter
+import pathlib
+import sys
 
 from traitlets import (
     CaselessStrEnum,
@@ -225,16 +227,28 @@ def create_markdown(spec):
     parser = argparse.ArgumentParser(description='Description of your program')
     parser.add_argument('-f', '--format', choices=['json', 'json-pretty', 'markdown'], 
         help='Format to generate', default='json')
+    parser.add_argument('output', nargs='?', type=pathlib.Path)
     args = parser.parse_args()
     format = args.format
 
+    if args.output:
+        args.output.parent.mkdir(exist_ok=True)
+        output = open(args.output, mode='w', encoding='utf8')
+    else:
+        output = sys.stdout
+
     widgets_to_document = sorted(widgets.Widget._widget_types.items())
     spec = create_spec(widgets_to_document)
-    if format == 'json':
-        print(json.dumps(spec, sort_keys=True))
-    elif format == 'json-pretty':
-        print(json.dumps(spec, sort_keys=True,
-              indent=2, separators=(',', ': ')))
-    elif format == 'markdown':
-        # We go through the json engine to convert tuples to lists, etc.
-        print(create_markdown(json.loads(json.dumps(spec))))
+    try:
+        if format == 'json':
+            json.dump(spec, output, sort_keys=True)
+        elif format == 'json-pretty':
+            json.dump(spec, output, sort_keys=True,
+                indent=2, separators=(',', ': '))
+        elif format == 'markdown':
+            # We go through the json engine to convert tuples to lists, etc.
+            output.write(create_markdown(json.loads(json.dumps(spec))))
+        output.write('\n')
+    finally:
+        if args.output:
+            output.close()