Settings: Update settings docs and format

andrewhead · andrewhead · commit bf7cf85c3fe7 · 2020-02-04T20:59:17.000-08:00
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "nbgather",
-  "version": "0.5.1-beta.0",
+  "version": "0.5.1-beta.1",
   "keywords": [
     "jupyter",
     "jupyterlab"
diff --git a/schema/plugin.json b/schema/plugin.json
@@ -1,47 +1,32 @@
 {
-  "jupyter.lab.setting-icon-label": "Code Gathering Tools",
-  "title": "Gather",
-  "description": "Settings for \"nbgather\" plugin.",
+  "jupyter.lab.setting-icon-label": "nbgather",
+  "title": "ngbather",
+  "description": "Settings for nbgather.",
   "properties": {
-    "loggingEnabled": {
-      "title": "Share Interaction Logging Data",
-      "description": "Whether to report interaction logging data. If this is set to true, interaction telemetry data from your notebook will be uploaded to a research server. Log data does not include any of your code or data, though it does include summary data about your notebook (e.g., the number of cells and their execution counts). Should be off by default.",
+    "enableLogging": {
+      "title": "Logging: Enable Optional Logging (OFF by default, opt-in only)",
+      "description": "Whether this plugin should log your interactions. Logs include only anonymized notebook interaction events, and do not include code or data.",
       "type": ["boolean"],
       "default": false
     },
-    "loggingId": {
-      "title": "Unique Logging ID",
-      "description": "Only used if you set 'Share Interaction Logging Data' to true. Then this ID is associated with all events logged from your notebook, so that all of events from the same user can be associated together.",
+    "loggingTag": {
+      "title": "Logging: Tag (NULL by default)",
+      "description": "If logging is enabled, all log events will be uploaded with this tag.",
       "type": ["string", "null"],
       "default": null
     },
-    "analysis": {
-      "title": "Analysis options",
-      "description": "Rules for fine-tuning data-flow analysis. This is most useful for making gather more precise for external APIs. To define specs for how analyze external APIs, define the \"analysis.symbolTable.moduleMap\" property, following instructions at https://github.com/andrewhead/python-program-analysis#api-specs",
-      "type": "object",
-      "properties": {
-        "symbolTable": {
-          "description": "Options for initializing the symbol table.",
-          "properties": {
-            "loadDefaultModuleMap": {
-              "description": "Whether to load the default module map for the dataflow analyzer. Includes functions from\ncommon data analysis modules like 'matplotlib' and 'pandas'.",
-              "type": "boolean"
-            },
-            "moduleMap": {
-              "$ref": "#/definitions/JsonSpecs",
-              "description": "Extend the module map with this variable if you want to specify rules for the how functions\nfrom certain modules affect their arguments, to help the slicer be more precise. If\n'loadDefaultModuleMap' is true, then this module map will be merged with the default module\nmap using the lodash 'merge' function."
-            }
-          },
-          "type": "object"
-        }
-      },
-      "additionalProperties": false,
-      "default": {
-        "symbolTable": {
-          "loadDefaultModuleMap": true,
-          "moduleMap": {}
-        }
-      }
+    "loadDefaultModuleMap": {
+      "title": "Load Default Module Map",
+      "description": "If a 'moduleMap' is defined, merge the 'moduleMap' from user settings with the default module map from the 'python-program-analysis' npm module. If 'false', overwrite defaults.",
+      "type": "boolean",
+      "default": true
+    },
+    "moduleMap": {
+      "title": "Module Map for Program Slicing",
+      "description": "Define rules to help nbgather decide how to gather code in cases where it can't infer whether lines should be gathered or not. Valid values for this property are described at https://github.com/andrewhead/python-program-analysis#api-specs. If you change this option, you will need to refresh this browser tab before nbgather loads the new settings.",
+      "$ref": "#/definitions/JsonSpecs",
+      "default": {},
+      "additionalProperties": false
     }
   },
   "additionalProperties": false,
diff --git a/src/main/main.ts b/src/main/main.ts
@@ -1,7 +1,8 @@
 import {
   DataflowAnalyzer,
   DataflowAnalyzerOptions,
-  ExecutionLogSlicer
+  ExecutionLogSlicer,
+  JsonSpecs
 } from "@andrewhead/python-program-analysis";
 import { JupyterFrontEndPlugin, JupyterLab } from "@jupyterlab/application";
 import { ICommandPalette } from "@jupyterlab/apputils";
@@ -68,12 +69,23 @@ export class CodeGatheringExtension
     this._documentManager = documentManager;
     this._notebooks = notebooks;
     this._gatherModelRegistry = gatherModelRegistry;
-    settingRegistry.get("nbgather:plugin", "analysis").then(data => {
-      if (JSONExt.isObject(data.composite)) {
-        let dataCompositeObject = data.composite as unknown;
-        this._analysisOptions = dataCompositeObject as DataflowAnalyzerOptions;
-      }
-    });
+    settingRegistry
+      .get("nbgather:plugin", "loadDefaultModuleMap")
+      .then(data => {
+        if (JSONExt.isPrimitive(data.composite)) {
+          let loadDefaultModuleMap = data.composite as boolean;
+          settingRegistry.get("nbgather:plugin", "moduleMap").then(data => {
+            if (JSONExt.isObject(data)) {
+              this._analysisOptions = {
+                symbolTable: {
+                  loadDefaultModuleMap,
+                  moduleMap: data.composite as JsonSpecs
+                }
+              };
+            }
+          });
+        }
+      });
   }
 
   createNew(
diff --git a/src/overlay/revision-browser.ts b/src/overlay/revision-browser.ts
@@ -1,7 +1,11 @@
 import { PanelLayout, Widget } from "@phosphor/widgets";
 import { GatherModel, GatherState } from "../model";
 import { log } from "../util/log";
-import { buildHistoryModel, HistoryViewer } from "../widgets/history";
+import {
+  buildHistoryModel,
+  HistoryViewer,
+  HISTORY_VIEWER_ICON_CLASS
+} from "../widgets/history";
 
 /**
  * Class for the revision browser widget.
@@ -18,8 +22,8 @@ export class RevisionBrowser extends Widget {
   constructor(gatherModel: GatherModel) {
     super();
     this.id = "revision-browser";
-    this.title.label = "Revision browser";
-    this.title.icon = "jp-HistoryIcon";
+    this.title.label = "Version Browser";
+    this.title.icon = HISTORY_VIEWER_ICON_CLASS;
     this.title.closable = true;
     this.addClass(REVISION_BROWSER_CLASS);
 
@@ -38,7 +42,9 @@ export class RevisionBrowser extends Widget {
     } else if (outputSelections.length > 0) {
       selectedCell = outputSelections[0].cell;
     }
-    let slices = model.executionLog.sliceAllExecutions(selectedCell.persistentId);
+    let slices = model.executionLog.sliceAllExecutions(
+      selectedCell.persistentId
+    );
     log("Bringing up the revision browser for selection", {
       cellExecutionEventId: selectedCell.executionEventId,
       slices,
@@ -50,7 +56,12 @@ export class RevisionBrowser extends Widget {
        * Only show output if the selection was output.
        */
       let includeOutput = model.selectedOutputs.length >= 1;
-      let historyModel = buildHistoryModel(model, selectedCell.persistentId, slices, includeOutput);
+      let historyModel = buildHistoryModel(
+        model,
+        selectedCell.persistentId,
+        slices,
+        includeOutput
+      );
       let historyViewer = new HistoryViewer({
         model: historyModel
       });
diff --git a/src/util/log.ts b/src/util/log.ts
@@ -1,5 +1,5 @@
-import { ISettingRegistry } from '@jupyterlab/coreutils';
-import * as $ from 'jquery';
+import { ISettingRegistry } from "@jupyterlab/coreutils";
+// import * as $ from "jquery";
 
 let _settingRegistry: ISettingRegistry;
 
@@ -38,56 +38,57 @@ export function registerPollers(...pollers: IStatePoller[]) {
 export function log(eventName: string, data?: any) {
   data = data || {};
 
-  let LOG_ENDPOINT = 'https://clarence.eecs.berkeley.edu';
+  // let LOG_ENDPOINT = "https://clarence.eecs.berkeley.edu";
 
   // Prepare log data.
   let postData: any = {
     timestamp: new Date().toISOString(),
     event: eventName,
     data: data,
-    loggingId: undefined,
+    tag: undefined
   };
 
   if (_settingRegistry != undefined || _settingRegistry != null) {
     _settingRegistry
-      .get('nbgather:plugin', 'loggingEnabled')
+      .get("nbgather:plugin", "enableLogging")
       .then(loggingEnabled => {
         if (
-          typeof loggingEnabled.composite === 'boolean' &&
+          typeof loggingEnabled.composite === "boolean" &&
           loggingEnabled.composite
         ) {
-          _settingRegistry
-            .get('nbgather:plugin', 'loggingId')
-            .then(loggingId => {
-              if (typeof loggingId.composite === 'string') {
-                postData.loggingId = loggingId.composite as string;
+          _settingRegistry.get("nbgather:plugin", "loggingTag").then(tag => {
+            if (typeof tag.composite === "string") {
+              postData.tag = tag.composite as string;
 
-                // Poll for additional data from each state poller.
-                for (let poller of _statePollers) {
-                  let pollData = poller.poll();
-                  for (let k in pollData) {
-                    if (pollData.hasOwnProperty(k)) {
-                      postData[k] = pollData[k];
-                    }
+              // Poll for additional data from each state poller.
+              for (let poller of _statePollers) {
+                let pollData = poller.poll();
+                for (let k in pollData) {
+                  if (pollData.hasOwnProperty(k)) {
+                    postData[k] = pollData[k];
                   }
                 }
+              }
 
-                // If there is any sensitive data to be logged, it should first be cleaned through a
-                // `toJSON` method defined on a class, or manually before passing it into this method.
-                // Earlier, we used the replacer argument to JSON.stringify, but it takes too much time
-                // to apply replacers to every value in the resulting JSON.
-                postData.data = JSON.stringify(postData.data);
+              // If there is any sensitive data to be logged, it should first be cleaned through a
+              // `toJSON` method defined on a class, or manually before passing it into this method.
+              // Earlier, we used the replacer argument to JSON.stringify, but it takes too much time
+              // to apply replacers to every value in the resulting JSON.
+              postData.data = JSON.stringify(postData.data);
 
-                // Submit data to logger endpoint.
-                $.ajax(LOG_ENDPOINT + '/log', {
-                  data: postData,
-                  method: 'POST',
-                  error: (_: any, textStatus: string, errorThrown: string) => {
-                    console.error('Failed to log', textStatus, errorThrown);
-                  },
-                });
-              }
-            });
+              // Submit data to logger endpoint.
+              // Disabled in the near term, until a new server is launched.
+              /*
+              $.ajax(LOG_ENDPOINT + "/log", {
+                data: postData,
+                method: "POST",
+                error: (_: any, textStatus: string, errorThrown: string) => {
+                  console.error("Failed to log", textStatus, errorThrown);
+                }
+              });
+              */
+            }
+          });
         }
       });
   }
diff --git a/src/widgets/history/widget.ts b/src/widgets/history/widget.ts
@@ -1,15 +1,15 @@
-import { PanelLayout, Widget } from '@phosphor/widgets';
-import { Revision } from '../revision';
-import { IHistoryModel } from './model';
+import { PanelLayout, Widget } from "@phosphor/widgets";
+import { Revision } from "../revision";
+import { IHistoryModel } from "./model";
 
 /**
  * The class name added to history viewer widgets
  */
-const HISTORY_VIEWER_CLASS = 'jp-HistoryViewer';
+const HISTORY_VIEWER_CLASS = "jp-HistoryViewer";
 
-const HISTORY_VIEWER_ICON_CLASS = 'jp-HistoryViewerIcon';
+export const HISTORY_VIEWER_ICON_CLASS = "jp-HistoryViewerIcon";
 
-const REFERENCE_VERSION_CLASS = 'jp-HistoryViewer-referenceversion';
+const REFERENCE_VERSION_CLASS = "jp-HistoryViewer-referenceversion";
 
 /**
  * A widget for showing the history of a result and how it was produced.
@@ -22,8 +22,8 @@ export class HistoryViewer extends Widget {
     super();
 
     this.addClass(HISTORY_VIEWER_CLASS);
-    this.id = 'livecells-revision-browser';
-    this.title.label = 'Revision Browser';
+    this.id = "livecells-revision-browser";
+    this.title.label = "Version Browser";
     this.title.icon = HISTORY_VIEWER_ICON_CLASS;
     this.title.closable = true;
 
@@ -36,7 +36,7 @@ export class HistoryViewer extends Widget {
     const now = new Date();
     let referenceVersion = new Revision({
       model: this._model.revisions[this._model.revisions.length - 1],
-      now: now,
+      now: now
     });
     referenceVersion.addClass(REFERENCE_VERSION_CLASS);
     layout.addWidget(referenceVersion);
@@ -48,7 +48,7 @@ export class HistoryViewer extends Widget {
         layout.addWidget(
           new Revision({
             model: revisionModel,
-            now: now,
+            now: now
           })
         );
       }

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "nbgather",`
`3`		`- "version": "0.5.1-beta.0",`
	`3`	`+ "version": "0.5.1-beta.1",`
`4`	`4`	`"keywords": [`
`5`	`5`	`"jupyter",`
`6`	`6`	`"jupyterlab"`