[fix][test] Fixed Nondeterministic Ordering in Generated Docs Topics (#24973)

Author: LucasEby

pulsar-docs-tools/src/main/java/org/apache/pulsar/docs/tools/CmdGenerateDocs.java

@@ -108,7 +108,7 @@ private String generateDocument(String module, CommandLine commander) {
                     sb.append("```shell\n$ ");
                     sb.append(this.commander.getCommandName()).append(" ");
                     sb.append(module).append(" ").append(subK).append(" options").append("\n```\n\n");
-                    List<ArgSpec> argSpecs = subV.getCommandSpec().args();
+                    List<ArgSpec> argSpecs = getSortedArgs(subV.getCommandSpec().args());
                     if (argSpecs.size() > 0) {
                         sb.append("|Flag|Description|Default|\n");
                         sb.append("|---|---|---|\n");
@@ -128,7 +128,7 @@ private String generateDocument(String module, CommandLine commander) {
             sb.append(" options").append("\n```").append("\n\n");
             sb.append("|Flag|Description|Default|\n");
             sb.append("|---|---|---|\n");
-            List<ArgSpec> argSpecs = commander.getCommandSpec().args();
+            List<ArgSpec> argSpecs = getSortedArgs(commander.getCommandSpec().args());
             argSpecs.forEach(option -> {
                 if (option.hidden() || !(option instanceof OptionSpec)) {
                     return;
@@ -144,6 +144,27 @@ private String generateDocument(String module, CommandLine commander) {
         return sb.toString();
     }
 
+    /**
+     * Returns a sorted copy of the argument specifications list, ordered by the
+     * OptionSpec order attribute for option specs. Non-option arguments
+     * retain their relative ordering.
+     *
+     * @param args the list of argument specifications to sort
+     * @return a new sorted list
+     */
+    private List<ArgSpec> getSortedArgs(List<ArgSpec> args) {
+        List<ArgSpec> sorted = new ArrayList<>(args);
+        sorted.sort((a, b) -> {
+            if (a instanceof OptionSpec && b instanceof OptionSpec) {
+                OptionSpec optA = (OptionSpec) a;
+                OptionSpec optB = (OptionSpec) b;
+                return Integer.compare(optA.order(), optB.order());
+            }
+            return 0;
+        });
+        return sorted;
+    }
+
     @Override
     public Integer call() throws Exception {
         if (commandNames.size() == 0) {

pulsar-docs-tools/src/test/java/org/apache/pulsar/docs/tools/CmdGenerateDocsTest.java

@@ -29,10 +29,10 @@ public class CmdGenerateDocsTest {
 
     @Command
     public class Arguments {
-        @Option(names = {"-h", "--help"}, description = "Show this help message")
+        @Option(names = {"-h", "--help"}, description = "Show this help message", order = 0)
         private boolean help = false;
 
-        @Option(names = {"-n", "--name"}, description = "Name")
+        @Option(names = {"-n", "--name"}, description = "Name", order = 1)
         private String name;
     }