Add OpenRPC documentation to JSON RPC methods

This does not cover providing documentation for all of the JSON RPC methods. It adds the framework for documentation and a fraction of the documentation itself to demonstrate.
paranext · Dec 10, 2024 · 067296f · 067296f
1 parent aaa1b44
commit 067296f
Show file tree

Hide file tree

Showing 26 changed files with 1,234 additions and 116 deletions.
diff --git a/cspell.json b/cspell.json
@@ -60,6 +60,7 @@
     "newtonsoft",
     "nodebuffer",
     "nums",
+    "openrpc",
     "papi",
     "papis",
     "paranext",

diff --git a/extensions/src/hello-someone/src/main.ts b/extensions/src/hello-someone/src/main.ts
@@ -301,6 +301,23 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
     (name: string) => {
       return `Hello ${name}!`;
     },
+    {
+      method: {
+        summary: 'Say hello to someone',
+        params: [
+          {
+            name: 'name',
+            required: true,
+            summary: 'Name of the person to say hello to',
+            schema: { type: 'string' },
+          },
+        ],
+        result: {
+          name: 'greeting',
+          schema: { type: 'string' },
+        },
+      },
+    },
   );
 
   // Create a webview or get the existing webview if ours already exists

diff --git a/extensions/src/platform-scripture-editor/src/main.ts b/extensions/src/platform-scripture-editor/src/main.ts
@@ -326,11 +326,47 @@ export async function activate(context: ExecutionActivationContext): Promise<voi
   const openPlatformScriptureEditorPromise = papi.commands.registerCommand(
     'platformScriptureEditor.openScriptureEditor',
     openPlatformScriptureEditor,
+    {
+      method: {
+        summary: 'Open the scripture editor for a project',
+        params: [
+          {
+            name: 'projectId',
+            required: false,
+            summary: 'The project ID to open the scripture editor for',
+            schema: { type: 'string' },
+          },
+        ],
+        result: {
+          name: 'return value',
+          summary: 'The ID of the opened web view',
+          schema: { type: 'string' },
+        },
+      },
+    },
   );
 
   const openPlatformResourceViewerPromise = papi.commands.registerCommand(
     'platformScriptureEditor.openResourceViewer',
     openPlatformResourceViewer,
+    {
+      method: {
+        summary: 'Open the scripture editor in read-only mode for a project',
+        params: [
+          {
+            name: 'projectId',
+            required: false,
+            summary: 'The project ID to open the scripture editor for',
+            schema: { type: 'string' },
+          },
+        ],
+        result: {
+          name: 'return value',
+          summary: 'The ID of the opened web view',
+          schema: { type: 'string' },
+        },
+      },
+    },
   );
 
   const scriptureEditorWebViewProviderPromise = papi.webViewProviders.register(

diff --git a/extensions/src/platform-scripture/src/checks/extension-host-check-runner.service.ts b/extensions/src/platform-scripture/src/checks/extension-host-check-runner.service.ts
@@ -406,7 +406,18 @@ async function initialize(): Promise<void> {
           );
           unsubscribers.add(dataProvider.dispose);
           unsubscribers.add(
-            await papi.commands.registerCommand('platformScripture.registerCheck', registerCheck),
+            await papi.commands.registerCommand('platformScripture.registerCheck', registerCheck, {
+              method: {
+                summary: 'Register a new check to run on the platform',
+                description:
+                  'This will only run properly within the extension host. Do not call this from the websocket. Instead implement a check runner.',
+                params: [],
+                result: {
+                  name: 'return value',
+                  schema: {},
+                },
+              },
+            }),
           );
           resolve();
         } catch (error) {

diff --git a/extensions/src/platform-scripture/src/main.ts b/extensions/src/platform-scripture/src/main.ts
@@ -173,6 +173,24 @@ export async function activate(context: ExecutionActivationContext) {
       await papi.settings.set('platformScripture.includeMyParatext9Projects', newSettingValue);
       return newSettingValue;
     },
+    {
+      method: {
+        summary: 'Toggle whether to include My Paratext 9 projects within the platform',
+        params: [
+          {
+            name: 'shouldInclude',
+            required: false,
+            summary: 'Whether to include My Paratext 9 projects',
+            schema: { type: 'boolean' },
+          },
+        ],
+        result: {
+          name: 'return value',
+          summary: 'The new value of the setting',
+          schema: { type: 'boolean' },
+        },
+      },
+    },
   );
   const includeProjectsValidatorPromise = papi.settings.registerValidator(
     'platformScripture.includeMyParatext9Projects',
@@ -197,6 +215,24 @@ export async function activate(context: ExecutionActivationContext) {
   const openCharactersInventoryPromise = papi.commands.registerCommand(
     'platformScripture.openCharactersInventory',
     openPlatformCharactersInventory,
+    {
+      method: {
+        summary: 'Open the characters inventory',
+        params: [
+          {
+            name: 'webViewId',
+            required: false,
+            summary: 'The ID of the web view tied to the project that the inventory is for',
+            schema: { type: 'string' },
+          },
+        ],
+        result: {
+          name: 'return value',
+          summary: 'The ID of the opened characters inventory web view',
+          schema: { type: 'string' },
+        },
+      },
+    },
   );
   const characterInventoryWebViewProviderPromise = papi.webViewProviders.register(
     characterInventoryWebViewType,
@@ -213,6 +249,24 @@ export async function activate(context: ExecutionActivationContext) {
   const openRepeatedWordsInventoryPromise = papi.commands.registerCommand(
     'platformScripture.openRepeatedWordsInventory',
     openPlatformRepeatedWordsInventory,
+    {
+      method: {
+        summary: 'Open the repeated words inventory',
+        params: [
+          {
+            name: 'webViewId',
+            required: false,
+            summary: 'The ID of the web view tied to the project that the inventory is for',
+            schema: { type: 'string' },
+          },
+        ],
+        result: {
+          name: 'return value',
+          summary: 'The ID of the opened repeated words inventory web view',
+          schema: { type: 'string' },
+        },
+      },
+    },
   );
   const repeatableWordsInventoryWebViewProviderPromise = papi.webViewProviders.register(
     repeatedWordsInventoryWebViewType,
@@ -229,6 +283,24 @@ export async function activate(context: ExecutionActivationContext) {
   const openMarkersInventoryPromise = papi.commands.registerCommand(
     'platformScripture.openMarkersInventory',
     openPlatformMarkersInventory,
+    {
+      method: {
+        summary: 'Open the markers inventory',
+        params: [
+          {
+            name: 'webViewId',
+            required: false,
+            summary: 'The ID of the web view tied to the project that the inventory is for',
+            schema: { type: 'string' },
+          },
+        ],
+        result: {
+          name: 'return value',
+          summary: 'The ID of the new open markers inventory web view',
+          schema: { type: 'string' },
+        },
+      },
+    },
   );
   const markersInventoryWebViewProviderPromise = papi.webViewProviders.register(
     markersInventoryWebViewType,
@@ -237,6 +309,24 @@ export async function activate(context: ExecutionActivationContext) {
   const configureChecksPromise = papi.commands.registerCommand(
     'platformScripture.openConfigureChecks',
     configureChecks,
+    {
+      method: {
+        summary: 'Open the configure checks web view',
+        params: [
+          {
+            name: 'webViewId',
+            required: false,
+            summary: 'The ID of the web view tied to the project that the checks are for',
+            schema: { type: 'string' },
+          },
+        ],
+        result: {
+          name: 'return value',
+          summary: 'The ID of the new configure checks web view',
+          schema: { type: 'string' },
+        },
+      },
+    },
   );
   const configureChecksWebViewProviderPromise = papi.webViewProviders.register(
     configureChecksWebViewType,
@@ -245,6 +335,24 @@ export async function activate(context: ExecutionActivationContext) {
   const showCheckResultsPromise = papi.commands.registerCommand(
     'platformScripture.showCheckResults',
     showCheckResults,
+    {
+      method: {
+        summary: 'Show the check results',
+        params: [
+          {
+            name: 'webViewId',
+            required: false,
+            summary: 'The ID of the web view tied to the project that the checks are for',
+            schema: { type: 'string' },
+          },
+        ],
+        result: {
+          name: 'return value',
+          summary: 'The ID of the new check results web view',
+          schema: { type: 'string' },
+        },
+      },
+    },
   );
   const showCheckResultsWebViewProviderPromise = papi.webViewProviders.register(
     checkResultsListWebViewType,