include generated documentation via the cli and integration with antora

ClusterlessHQ · Aug 3, 2023 · 6b5e5a9 · 6b5e5a9
1 parent 6c1069c
commit 6b5e5a9
Show file tree

Hide file tree

Showing 13 changed files with 317 additions and 92 deletions.
diff --git a/antora.yml b/antora.yml
@@ -0,0 +1,10 @@
+name: clusterless
+title: Clusterless Reference
+version: wip-1.0
+ext:
+  collector:
+    run:
+      command: ./gradlew generateDocs -i
+    scan:
+      dir: clusterless-main/build/docs
+
diff --git a/build-logic/src/main/kotlin/clusterless.java-common-conventions.gradle.kts b/build-logic/src/main/kotlin/clusterless.java-common-conventions.gradle.kts
@@ -19,10 +19,17 @@ val versionProperties = Properties().apply {
     load(FileInputStream(File(rootProject.rootDir, "version.properties")))
 }
 
-val release = false;
+val release = false; // test if release branch
 val buildNumber = System.getenv("GITHUB_RUN_NUMBER") ?: "dev"
 val wipReleases = "wip-${buildNumber}"
 
+
+val versionLabel = if (release)
+    "${versionProperties["clusterless.release.major"]}-${versionProperties["clusterless.release.minor"]}"
+else "${versionProperties["clusterless.release.major"]}-wip"
+
+ext.set("versionLabel", versionLabel)
+
 version = if (release)
     "${versionProperties["clusterless.release.major"]}-${versionProperties["clusterless.release.minor"]}"
 else "${versionProperties["clusterless.release.major"]}-${wipReleases}"

diff --git a/clusterless-main-common/build.gradle.kts b/clusterless-main-common/build.gradle.kts
@@ -15,4 +15,5 @@ dependencies {
     implementation(project(":clusterless-model"))
 
     implementation("info.picocli:picocli")
-}
+    implementation("com.github.jknack:handlebars")
+}
diff --git a/clusterless-main-common/src/main/java/clusterless/printer/Printer.java b/clusterless-main-common/src/main/java/clusterless/printer/Printer.java
@@ -8,19 +8,38 @@
 
 package clusterless.printer;
 
+import com.github.jknack.handlebars.Context;
+import com.github.jknack.handlebars.Handlebars;
+import com.github.jknack.handlebars.Options;
+import com.github.jknack.handlebars.Template;
+import com.github.jknack.handlebars.context.MapValueResolver;
+import com.github.jknack.handlebars.helper.StringHelpers;
 import picocli.CommandLine;
 
-import java.io.OutputStreamWriter;
-import java.io.PrintStream;
-import java.io.Writer;
+import java.io.*;
 import java.util.Collection;
+import java.util.Map;
+
+import static com.github.jknack.handlebars.internal.lang3.Validate.notNull;
 
 /**
  *
  */
 public class Printer {
-    @CommandLine.Option(names = {"-j", "--json"}, description = "print results as json")
+    @CommandLine.Option(
+            names = {"-j", "--json"},
+            description = "print results as json",
+            hidden = true
+    )
     boolean json = false;
+    private static final Handlebars handlebars = new Handlebars()
+            .prettyPrint(false);
+
+    static {
+        StringHelpers.register(handlebars);
+        handlebars.registerHelper("indent", Printer::indent);
+    }
+
     private PrintStream out = System.out;
 
     public Printer() {
@@ -37,4 +56,28 @@ public void println(String string) {
     public Writer writer() {
         return new OutputStreamWriter(out);
     }
+
+    public void writeWithTemplate(String template, Map<String, Object> params, Writer writer) {
+        try {
+            Context context = Context
+                    .newBuilder(params)
+                    .resolver(
+                            MapValueResolver.INSTANCE
+                    )
+                    .build();
+
+            Template compile = handlebars.compile(template);
+
+            compile.apply(context, writer);
+            writer.flush();
+        } catch (IOException e) {
+            throw new UncheckedIOException(e);
+        }
+    }
+
+    protected static CharSequence indent(final Object value, final Options options) {
+        Integer width = options.param(0, 4);
+        notNull(width, "found 'null', expected 'indent'");
+        return value.toString().trim().indent(width);
+    }
 }
diff --git a/clusterless-main/build.gradle.kts b/clusterless-main/build.gradle.kts
@@ -96,3 +96,63 @@ tasks.register("release") {
     dependsOn("distZip")
     dependsOn("jreleaserRelease")
 }
+
+tasks.register<Exec>("generateComponentDocs") {
+    dependsOn("installDist")
+
+    workingDir = file("build/install/clusterless/bin")
+    commandLine = listOf(
+        "cls",
+        "show",
+        "component",
+        "--describe-all",
+        "--output",
+        "${buildDir}/generated-docs/modules/components"
+    )
+}
+
+tasks.register<Exec>("generateComponentIndex") {
+    dependsOn("installDist")
+
+    workingDir = file("build/install/clusterless/bin")
+    commandLine = listOf(
+        "cls",
+        "show",
+        "component",
+        "--list",
+        "--output",
+        "${buildDir}/generated-docs/modules/components/"
+    )
+}
+
+tasks.register<Exec>("generateComponentPartial") {
+    dependsOn("installDist")
+
+    workingDir = file("build/install/clusterless/bin")
+    commandLine = listOf(
+        "cls",
+        "show",
+        "component",
+        "--list",
+        "--output",
+        "${buildDir}/generated-docs/modules/components/partials",
+        "--name",
+        "components.adoc",
+        "--template",
+        "components-list-partial-adoc"
+    )
+}
+
+tasks.register<Copy>("generateDocs") {
+    dependsOn("generateComponentDocs")
+    dependsOn("generateComponentIndex")
+    dependsOn("generateComponentPartial")
+
+    from("src/main/antora") {
+        filter {
+            it.replace("{{projectVersion}}", project.ext["versionLabel"].toString())
+        }
+    }
+    from("${buildDir}/generated-docs/")
+    into("${buildDir}/docs/")
+}
diff --git a/clusterless-main/src/main/antora/antora.yml b/clusterless-main/src/main/antora/antora.yml
@@ -0,0 +1,6 @@
+name: reference
+title: Clusterless Reference
+version: {{projectVersion}}
+start_page: reference::index.adoc
+nav:
+  - modules/components/nav.adoc
diff --git a/clusterless-main/src/main/antora/modules/ROOT/pages/index.adoc b/clusterless-main/src/main/antora/modules/ROOT/pages/index.adoc
@@ -0,0 +1,27 @@
+= Clusterless Reference
+
+== Command Line
+
+The Clusterless application is a command line utility named `cls`.
+
+`cls --help` is the starting point for the usage documentation.
+
+== Providers
+
+Currently, only Amazon Web Services (AWS) is supported.
+
+== Components
+
+Components are either:
+
+* xref:guide:concepts:resource.adoc[Resources]
+* xref:guide:concepts:boundary.adoc[Boundaries]
+* xref:guide:concepts:arc.adoc[Arcs]
+
+All components:
+
+include::reference:components:partial$components.adoc[]
+
+== Models
+
+The Clusterless project file has a number of JSON objects or models that need to be provided in order to create a valid clusterless deployable project.
diff --git a/clusterless-main/src/main/java/clusterless/ShowCommand.java b/clusterless-main/src/main/java/clusterless/ShowCommand.java
@@ -55,7 +55,7 @@ static class Exclusive {
 
             @SuppressWarnings("OptionalUsedAsFieldOrParameterType")
             @CommandLine.Option(
-                    names = "--template",
+                    names = "--model",
                     arity = "1",
                     description = "print the json template of element"
             )
@@ -82,7 +82,7 @@ public Integer call() throws Exception {
             } else if (exclusive.list.isPresent() && exclusive.list.get()) {
                 return handleList();
             } else if (exclusive.template.isPresent()) {
-                return handleTemplte();
+                return handleTemplate();
             } else if (exclusive.component.isPresent()) {
                 return handleDescribe();
             }
@@ -94,7 +94,7 @@ protected Integer handleList() throws Exception {
             return 0;
         }
 
-        protected Integer handleTemplte() throws Exception {
+        protected Integer handleTemplate() throws Exception {
             return 0;
         }