JSONGenerator for addons and docs.json improvements (#8116)

Efnilite · APickledWalrus · web-flow · commit 2826897cde2e · 2025-09-17T22:07:00.000+02:00
* init commit

* add docs

* add StructEvent docs

* requested changes

* fix default values for DocumentationGenerator

* github why won't you work

* attempt to fix getting skript version in generate-docs action

* attempt to fix getting skript version in generate-docs action

* requested changes

* requested changes

* requested changes

* thx bbg burb

* Update src/main/java/ch/njol/skript/doc/JSONGenerator.java

Co-authored-by: Patrick Miller &lt;apickledwalrus@icloud.com&gt;

---------

Co-authored-by: Patrick Miller &lt;apickledwalrus@icloud.com&gt;
diff --git a/.github/workflows/docs/generate-docs/action.yml b/.github/workflows/docs/generate-docs/action.yml
@@ -52,10 +52,8 @@ runs:
           find $1 -type f -exec sed -i -e "s/$2/$3/g" {} \;
         }
 
-        # this should be replaced with a more reliable jq command,
-        # but it can't be right now because docs.json is actually not valid json.
         get_skript_version_of_directory() {
-          grep skriptVersion "$1/docs.json" | cut -d\" -f 4
+          jq ".source.version" "$1/docs.json"
         }
 
         if [ -d "${DOCS_REPO_DIR}/docs/templates" ]
diff --git a/src/main/java/ch/njol/skript/SkriptCommand.java b/src/main/java/ch/njol/skript/SkriptCommand.java
@@ -386,8 +386,9 @@ public boolean onCommand(CommandSender sender, Command command, String label, St
 				outputDir.mkdirs();
 
 				Skript.info(sender, "Generating docs...");
-				JSONGenerator jsonGenerator = new JSONGenerator(templateDir, outputDir);
-				jsonGenerator.generate();
+
+				JSONGenerator.of(Skript.instance())
+					.generate(outputDir.toPath().resolve("docs.json"));
 
 				if (!templateDir.exists()) {
 					Skript.info(sender, "JSON-only documentation generated!");
diff --git a/src/main/java/ch/njol/skript/doc/DocumentationGenerator.java b/src/main/java/ch/njol/skript/doc/DocumentationGenerator.java
@@ -1,10 +1,12 @@
 package ch.njol.skript.doc;
 
 import java.io.File;
+import java.nio.file.Path;
 
 /**
- * Represents a class which generates a documentation format (like HTML or JSON)
+ * @deprecated Use {@link JSONGenerator} instead.
  */
+@Deprecated(forRemoval = true, since = "INSERT VERSION")
 public abstract class DocumentationGenerator {
 
 	protected File templateDir;
@@ -16,8 +18,9 @@ public DocumentationGenerator(File templateDir, File outputDir) {
 	}
 
 	/**
-	 * Generates the documentation file
+	 * Use {@link JSONGenerator#generate(Path)} instead.
 	 */
+	@Deprecated(forRemoval = true, since = "INSERT VERSION")
 	public abstract void generate();
 
 }
diff --git a/src/main/java/ch/njol/skript/doc/DocumentationIdProvider.java b/src/main/java/ch/njol/skript/doc/DocumentationIdProvider.java
@@ -12,6 +12,7 @@
 import ch.njol.skript.lang.function.Functions;
 import ch.njol.skript.registrations.Classes;
 import org.skriptlang.skript.lang.structure.Structure;
+import org.skriptlang.skript.registration.SyntaxInfo;
 
 import java.util.Arrays;
 import java.util.Iterator;
@@ -62,7 +63,16 @@ private static <T> int calculateCollisionCount(Iterator<? extends T> potentialCo
 	 * @return the ID of the syntax element
 	 */
 	public static <T> String getId(SyntaxElementInfo<? extends T> syntaxInfo) {
-		Class<?> syntaxClass = syntaxInfo.getElementClass();
+		return getId((SyntaxInfo<?>) syntaxInfo);
+	}
+
+	/**
+	 * Gets the documentation ID of a syntax element
+	 * @param syntaxInfo the SyntaxInfo to get the ID of
+	 * @return the ID of the syntax element
+	 */
+	public static <T> String getId(SyntaxInfo<? extends T> syntaxInfo) {
+		Class<?> syntaxClass = syntaxInfo.type();
 		Iterator<? extends SyntaxElementInfo<?>> syntaxElementIterator;
 		if (Effect.class.isAssignableFrom(syntaxClass)) {
 			syntaxElementIterator = Skript.getEffects().iterator();
@@ -79,7 +89,7 @@ public static <T> String getId(SyntaxElementInfo<? extends T> syntaxInfo) {
 		}
 		int collisionCount = calculateCollisionCount(syntaxElementIterator,
 			elementInfo -> elementInfo.getElementClass() == syntaxClass,
-			elementInfo -> Arrays.equals(elementInfo.getPatterns(), syntaxInfo.getPatterns()));
+			elementInfo -> Arrays.equals(elementInfo.getPatterns(), syntaxInfo.patterns().toArray(new String[0])));
 		DocumentationId documentationIdAnnotation = syntaxClass.getAnnotation(DocumentationId.class);
 		if (documentationIdAnnotation == null) {
 			return addCollisionSuffix(syntaxClass.getSimpleName(), collisionCount);
diff --git a/src/main/java/ch/njol/skript/doc/HTMLGenerator.java b/src/main/java/ch/njol/skript/doc/HTMLGenerator.java
@@ -37,7 +37,6 @@
 /**
  * Template engine, primarily used for generating Skript documentation
  * pages by combining data from annotations and templates.
- *
  */
 public class HTMLGenerator extends DocumentationGenerator {
 
diff --git a/src/main/java/ch/njol/skript/doc/JSONGenerator.java b/src/main/java/ch/njol/skript/doc/JSONGenerator.java
diff --git a/src/main/java/ch/njol/skript/structures/StructEvent.java b/src/main/java/ch/njol/skript/structures/StructEvent.java

Original file line number	Diff line number	Diff line change
`@@ -52,10 +52,8 @@ runs:`
`52`	`52`	`find $1 -type f -exec sed -i -e "s/$2/$3/g" {} \;`
`53`	`53`	`}`
`54`	`54`
`55`		`- # this should be replaced with a more reliable jq command,`
`56`		`- # but it can't be right now because docs.json is actually not valid json.`
`57`	`55`	`get_skript_version_of_directory() {`
`58`		`- grep skriptVersion "$1/docs.json" \| cut -d\" -f 4`
	`56`	`+ jq ".source.version" "$1/docs.json"`
`59`	`57`	`}`
`60`	`58`
`61`	`59`	`if [ -d "${DOCS_REPO_DIR}/docs/templates" ]`