Jsdocs api plugins generation script

ONLYOFFICE · Aug 5, 2024 · 9a44dae · 9a44dae
1 parent 07665dd
commit 9a44dae
Show file tree

Hide file tree

Showing 14 changed files with 326 additions and 10 deletions.
diff --git a/scripts/sdkjs_common/jsdoc/README.md b/scripts/sdkjs_common/jsdoc/README.md
@@ -1,7 +1,7 @@
 
 # Documentation Generation Guide
 
-This guide explains how to generate documentation for Onlyoffice API using the provided Python scripts, `generate_docs_json.py` and `generate_docs_md.py`. These scripts are used to create JSON and Markdown documentation for the `apiBuilder.js` files from the word, cell, and slide editors.
+This guide explains how to generate documentation for Onlyoffice Builder/Plugins API using the provided Python scripts: `generate_docs_json.py`, `generate_docs_plugins_json.py`, `generate_docs_md.py`. These scripts are used to create JSON and Markdown documentation for the `apiBuilder.js` files from the word, cell, and slide editors.
 
 ## Prerequisites
 
@@ -24,7 +24,19 @@ This script generates JSON documentation based on the `apiBuilder.js` files.
   ```
 
 - **Parameters**:
-  - `output_path` (optional): The directory where the JSON documentation will be saved. If not specified, the default path is `Onlyoffice/sdkjs/deploy/api_builder/json`.
+  - `output_path` (optional): The directory where the JSON documentation will be saved. If not specified, the default path is `Onlyoffice/document-builder-declarations/document-builder`.
+
+### `generate_docs_plugins_json.py`
+
+This script generates JSON documentation based on the `api_plugins.js` files.
+
+- **Usage**:
+  ```bash
+  python generate_docs_plugins_json.py output_path
+  ```
+
+- **Parameters**:
+  - `output_path` (optional): The directory where the JSON documentation will be saved. If not specified, the default path is `Onlyoffice/document-builder-declarations/document-builder-plugin`.
 
 ### `generate_docs_md.py`
 
@@ -45,6 +57,11 @@ To generate JSON documentation with the default output path:
 python generate_docs_json.py /path/to/save/json
 ```
 
+To generate JSON documentation with the default output path:
+```bash
+python generate_docs_plugins_json.py /path/to/save/json
+```
+
 To generate Markdown documentation and specify a custom output path:
 ```bash
 python generate_docs_md.py /path/to/save/markdown

diff --git a/scripts/sdkjs_common/jsdoc/config/cell.json → ...kjs_common/jsdoc/config/builder/cell.json b/scripts/sdkjs_common/jsdoc/config/cell.json → ...kjs_common/jsdoc/config/builder/cell.json
diff --git a/...js_common/jsdoc/config/correct_doclets.js → ...n/jsdoc/config/builder/correct_doclets.js b/...js_common/jsdoc/config/correct_doclets.js → ...n/jsdoc/config/builder/correct_doclets.js
diff --git a/scripts/sdkjs_common/jsdoc/config/forms.json → ...js_common/jsdoc/config/builder/forms.json b/scripts/sdkjs_common/jsdoc/config/forms.json → ...js_common/jsdoc/config/builder/forms.json
diff --git a/scripts/sdkjs_common/jsdoc/config/slide.json → ...js_common/jsdoc/config/builder/slide.json b/scripts/sdkjs_common/jsdoc/config/slide.json → ...js_common/jsdoc/config/builder/slide.json
diff --git a/scripts/sdkjs_common/jsdoc/config/word.json → ...kjs_common/jsdoc/config/builder/word.json b/scripts/sdkjs_common/jsdoc/config/word.json → ...kjs_common/jsdoc/config/builder/word.json
diff --git a/scripts/sdkjs_common/jsdoc/config/plugins/cell.json b/scripts/sdkjs_common/jsdoc/config/plugins/cell.json
@@ -0,0 +1,16 @@
+{
+  "source": {
+    "include": ["../../../../sdkjs/cell/api_plugins.js"]
+  },
+  "plugins": ["./correct_doclets.js"],
+  "opts": {
+    "destination": "./out",
+    "recurse": true,
+    "encoding": "utf8"
+  },
+  "templates": {
+    "json": {
+      "pretty": true
+    }
+  }
+}
diff --git a/scripts/sdkjs_common/jsdoc/config/plugins/common.json b/scripts/sdkjs_common/jsdoc/config/plugins/common.json
@@ -0,0 +1,16 @@
+{
+  "source": {
+    "include": ["../../../../sdkjs/common/plugins/plugin_base_api.js" ,"../../../../sdkjs/common/apiBase_plugins.js"]
+  },
+  "plugins": ["./correct_doclets.js"],
+  "opts": {
+    "destination": "./out",
+    "recurse": true,
+    "encoding": "utf8"
+  },
+  "templates": {
+    "json": {
+      "pretty": true
+    }
+  }
+}
diff --git a/scripts/sdkjs_common/jsdoc/config/plugins/correct_doclets.js b/scripts/sdkjs_common/jsdoc/config/plugins/correct_doclets.js
@@ -0,0 +1,85 @@
+exports.handlers = {
+    processingComplete: function(e) {
+        const filteredDoclets = [];
+
+        function checkNullProps(oDoclet) {
+            for (let key of Object.keys(oDoclet)) {
+                if (oDoclet[key] == null) {
+                    delete oDoclet[key];
+                }
+                if (typeof(oDoclet[key]) == "object") {
+                    checkNullProps(oDoclet[key]);
+                }
+            }
+        }
+
+        for (let i = 0; i < e.doclets.length; i++) {
+            const doclet = e.doclets[i];
+            if (true == doclet.undocumented || doclet.kind == 'package') {
+                continue;
+            }
+
+            const filteredDoclet = {
+                comment:        doclet.comment,
+
+                meta: doclet.meta ? {
+                    lineno:   doclet.meta.lineno,
+                    columnno: doclet.meta.columnno
+                } : doclet.meta,
+
+                kind:           doclet.kind,
+                since:          doclet.since,
+                name:           doclet.name,
+                type: doclet.type ? {
+                    names: doclet.type.names,
+                    parsedType: doclet.type.parsedType
+                } : doclet.type,
+
+                description:    doclet.description,
+                memberof:       doclet.memberof,
+
+                properties: doclet.properties ? doclet.properties.map(property => ({
+                    type: property.type ? {
+                        names:      property.type.names,
+                        parsedType: property.type.parsedType
+                    } : property.type,
+
+                    name:           property.name,
+                    description:    property.description,
+                    optional:       property.optional,
+                    defaultvalue:   property.defaultvalue
+                })) : doclet.properties,
+
+                longname:       doclet.longname,
+                scope:          doclet.scope,
+                alias:          doclet.alias,
+
+                params: doclet.params ? doclet.params.map(param => ({
+                    type: param.type ? {
+                        names:      param.type.names,
+                        parsedType: param.type.parsedType
+                    } : param.type,
+
+                    name:           param.name,
+                    description:    param.description,
+                    optional:       param.optional,
+                    defaultvalue:   param.defaultvalue
+                })) : doclet.params,
+
+                returns: doclet.returns ? doclet.returns.map(returnObj => ({
+                    type: {
+                      names:        returnObj.type.names,
+                      parsedType:   returnObj.type.parsedType
+                    }
+                })) : doclet.returns,
+                see: doclet.see
+            };
+
+            checkNullProps(filteredDoclet)
+
+            filteredDoclets.push(filteredDoclet);
+        }
+
+        e.doclets.splice(0, e.doclets.length, ...filteredDoclets);
+    }
+};
diff --git a/scripts/sdkjs_common/jsdoc/config/plugins/forms.json b/scripts/sdkjs_common/jsdoc/config/plugins/forms.json
@@ -0,0 +1,16 @@
+{
+  "source": {
+    "include": ["../../../../sdkjs-forms/apiPlugins.js"]
+  },
+  "plugins": ["./correct_doclets.js"],
+  "opts": {
+    "destination": "./out",
+    "recurse": true,
+    "encoding": "utf8"
+  },
+  "templates": {
+    "json": {
+      "pretty": true
+    }
+  }
+}
diff --git a/scripts/sdkjs_common/jsdoc/config/plugins/slide.json b/scripts/sdkjs_common/jsdoc/config/plugins/slide.json
@@ -0,0 +1,16 @@
+{
+  "source": {
+    "include": ["../../../../sdkjs/slide/api_plugins.js"]
+  },
+  "plugins": ["./correct_doclets.js"],
+  "opts": {
+    "destination": "./out",
+    "recurse": true,
+    "encoding": "utf8"
+  },
+  "templates": {
+    "json": {
+      "pretty": true
+    }
+  }
+}
diff --git a/scripts/sdkjs_common/jsdoc/config/plugins/word.json b/scripts/sdkjs_common/jsdoc/config/plugins/word.json
@@ -0,0 +1,16 @@
+{
+  "source": {
+    "include": ["../../../../sdkjs/word/api_plugins.js", "../../../../sdkjs-forms/apiPlugins.js"]
+  },
+  "plugins": ["./correct_doclets.js"],
+  "opts": {
+    "destination": "./out",
+    "recurse": true,
+    "encoding": "utf8"
+  },
+  "templates": {
+    "json": {
+      "pretty": true
+    }
+  }
+}
diff --git a/scripts/sdkjs_common/jsdoc/generate_docs_json.py b/scripts/sdkjs_common/jsdoc/generate_docs_json.py
@@ -4,12 +4,14 @@
 import argparse
 import re
 
+root = '../../../..'
+
 # Configuration files
 configs = [
-    "./config/word.json",
-    "./config/cell.json",
-    "./config/slide.json",
-    "./config/forms.json"
+    "./config/builder/word.json",
+    "./config/builder/cell.json",
+    "./config/builder/slide.json",
+    "./config/builder/forms.json"
 ]
 
 editors_maps = {
@@ -55,7 +57,7 @@ def generate(output_dir, md=False):
                     else:
                         doclet['see'][0] = doclet['see'][0].replace('{Editor}', editor_name.title())
 
-                    file_path = '../../../../' + doclet['see'][0]
+                    file_path = f'{root}/' + doclet['see'][0]
 
                     if os.path.exists(file_path):
                         with open(file_path, 'r', encoding='utf-8') as see_file:
@@ -85,7 +87,7 @@ def generate(output_dir, md=False):
         with open(output_file, 'w', encoding='utf-8') as f:
             json.dump(data, f, ensure_ascii=False, indent=4)
 
-    print("Documentation generation completed.")
+    print("Documentation generation for builder completed.")
 
 def remove_builder_lines(text):
     lines = text.splitlines()  # Split text into lines
@@ -125,11 +127,11 @@ def get_current_branch(path):
         type=str, 
         help="Destination directory for the generated documentation",
         nargs='?',  # Indicates the argument is optional
-        default="../../../../document-builder-declarations/document-builder"  # Default value
+        default=f"{root}/document-builder-declarations/document-builder"  # Default value
     )
     args = parser.parse_args()
 
-    branch_name = get_current_branch("../../../../sdkjs")
+    branch_name = get_current_branch(f"{root}/sdkjs")
     if branch_name:
         args.destination = f"{args.destination}/{branch_name}"