From a657eb555b5fa3d285799cff27390637fa25169d Mon Sep 17 00:00:00 2001
From: hlomzik <hlomzik@gmail.com>
Date: Tue, 10 Sep 2024 14:10:41 +0100
Subject: [PATCH] Update the way we run create-docs and generate schema.json

1. Switch to direct run `nx docs editor` instead of `nx run-many`,
   because we only have `docs` target in editor; it's faster and less confusing
2. Accept path to `schema.json` from env var `SCHEMA_JSON_PATH`:
   - no hardcoded value, configurable on a correct level
   - if no var is provided we just don't generate schema.json
   - this path can also be provided as a 2nd arg for create-docs just in case
3. Apply linting to schema.json, so it won't be rejected by biome check later
   - biome is applied directly in package.json command, so any usage will have a correct file
   - `;` after env var set is required to use it in the command in the same line
---
 web/libs/editor/scripts/create-docs.js | 28 +++++++++++++++++++++-----
 web/package.json                       |  2 +-
 2 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/web/libs/editor/scripts/create-docs.js b/web/libs/editor/scripts/create-docs.js
index 8432bac8f0a5..d665a275d500 100644
--- a/web/libs/editor/scripts/create-docs.js
+++ b/web/libs/editor/scripts/create-docs.js
@@ -1,3 +1,19 @@
+/**
+ * This file is used to parse JSDoc for every tag and their regions
+ * and generate two artifacts out of it:
+ * - tag docs for https://labelstud.io/tags/
+ *   generated docs are written to `outputDirArg` (1st arg)
+ * - schema.json — a dictionary for auto-complete in config editor
+ *   generated file is written to `schemaJsonPath` (2nd arg or `SCHEMA_JSON_PATH` env var)
+ *
+ * Special new constructions:
+ * - `@regions` to reference a Region tag(s) used by current tag
+ * - `@subtag` to mark a tag used inside other tag (only Channel for now)
+ *
+ * Usage:
+ *   node scripts/create-docs.js [path/to/docs/dir] [path/to/schema.json]
+ */
+
 const jsdoc2md = require("jsdoc-to-markdown");
 const fs = require("fs");
 const path = require("path");
@@ -49,8 +65,7 @@ const infoHeader = (name, group, isNew = false, meta = {}) =>
 const args = process.argv.slice(2);
 const outputDirArg = args[0] || `${__dirname}/../docs`;
 const outputDir = path.resolve(outputDirArg);
-// @todo more generic way to get schema dir?
-const outputSchemaDir = path.resolve(`${outputDir}/../../../web/apps/labelstudio/src/pages/CreateProject/Config`);
+const schemaJsonPath = args[1] || process.env.SCHEMA_JSON_PATH;
 
 // schema for CodeMirror autocomplete
 const schema = {};
@@ -194,8 +209,11 @@ fetch(currentTagsUrl)
       }
     }
 
-    // for now only hardcoded list of all tags for View
-    schema.View.children = Object.keys(schema).filter((name) => name !== "!top");
-    fs.writeFileSync(path.resolve(outputSchemaDir, "schema.json"), JSON.stringify(schema, null, 2));
+    if (schemaJsonPath) {
+      // @todo we can't generate correct children for every tag for some reason
+      // so for now we only specify children for the only root tag — View
+      schema.View.children = Object.keys(schema).filter((name) => name !== "!top");
+      fs.writeFileSync(schemaJsonPath, JSON.stringify(schema, null, 2));
+    }
   })
   .catch(console.error);
diff --git a/web/package.json b/web/package.json
index 6972b6558cdb..eaeefae84c3c 100644
--- a/web/package.json
+++ b/web/package.json
@@ -22,7 +22,7 @@
     "dm:unit": "nx run datamanager:unit",
     "build": "NODE_ENV=production yarn ls:build",
     "version:libs": "nx run-many --target=version",
-    "docs": "nx run-many --target=docs",
+    "docs": "SCHEMA_JSON_PATH=$PWD/apps/labelstudio/src/pages/CreateProject/Config/schema.json; nx docs editor && biome check --apply $SCHEMA_JSON_PATH",
     "watch": "NODE_ENV=development BUILD_NO_SERVER=true yarn ls:watch",
     "dev": "NODE_ENV=development BUILD_NO_SERVER=true yarn ls:dev",
     "test:e2e": "yarn ls:e2e && yarn lsf:e2e",