feat(core): Custom files per alias entries about their usage #9 (#12)

* feat(core): Custom files per alias entries about their usage #9

- Custom usage files for alias entries, with that the usage of the script can be detailed within code format as it will be rendered as a bash code

README.adoc

@@ -65,7 +65,7 @@ Catalogs (simple JSON files) can be put into a Git repository and other develope
     },
     "rodnansol": {
       "catalog-ref": "https://github.com/rodnansol/jbang-catalog/blob/HEAD/jbang-catalog.json",
-      "description": "RodnanSol JBang Catalog"
+      "description": "Rodnan Sol JBang Catalog"
     }
   },
   "aliases": {
@@ -200,9 +200,10 @@ Download the uber-jar/fatjar and run it with *Java 17*(!).
 [source,bash]
 ----
 java -jar jbang-catalog-document-generator-cli/target/jbang-catalog-document-generator-cli-999-SNAPSHOT.jar generate
-Usage: <main class> generate [-g] [-cc] [-hfdr] [-toc]
+Usage: <main class> generate [-g] [-cc] [-cus] [-hfdr] [-toc]
                              [-cf=<customFooterFilePath>]
                              [-ch=<customHeaderFilePath>] [-o=<outputFile>]
+                             [-pcn=<preferredCatalogName>]
                              [-t=<customTemplatePath>] [-toc-l=<tocLevels>]
                              [-toc-p=<tocPlacement>] [-toc-t=<tocTitle>]
                              [-tt=<templateType>] <inputFile>
@@ -215,6 +216,8 @@ Generates a documentation for a given jbang-catalog.json file
                     Path to a custom footer.
       -ch, --custom-header=<customHeaderFilePath>
                     Path to a custom header.
+      -cus, --collapsible-usage-section
+                    Defines if the usage section should be collapsible or not
   -g, --include-generation-date
                     Defines if the generation date should be put into the
                       document or not.
@@ -278,8 +281,62 @@ endif::[]
 
 == Customization options
 
+=== Custom header and footer
 Custom header and custom footer can be attached to make sure introductions and other important stuff can be put into the final document.
 
+=== Alias usages
+
+The alias entries can be extended with a help/usage section where the usage of the script can have a detailed description, for example if it is a CLI application the usage of the app or the flags can be put here.
+
+.Example jbang-catalog.json
+[source,json]
+----
+{
+  "aliases": {
+    "hello": {
+      "script-ref": "hello.java",
+      "description": "Script that says hello back for each argument"
+    }
+  }
+}
+----
+
+.hello.txt
+[source,txt]
+----
+This is a usage file, that will be rendered below the `hello` alias entry.
+
+!%$&@ So you want to use this script? !%$&@
+
+< Let me show you how you can use it. >
+----
+
+==== Result in AsciiDoc
+
+ifndef::env-github[]
+include::example$document-with-usage.adoc[]
+endif::[]
+ifdef::env-github[]
+include::docs/modules/ROOT/examples/document-with-usage.adoc[]
+endif::[]
+
+
+
+It can put behind a collapsible section with the `-cus` (`--collapsible-usage-section`) flag.
+
+'''
+=== Working directory
+
+Since the 0.2.0 version the current working directory can be overwritten which can help you to read the usages from a different path if you wish. It can be overwritten with the `-Dapp.document.current-working-directory=` flag when using the `java` command.
+
+.Example
+[source,bash]
+----
+java -Dapp.document.current-working-directory=new-working/directory -jar jbang-catalog-document-generator-cli.jar generate jbang-catalog.json
+----
+
+In this case the *alias* usages will be read from the *new-working/directory* folder.
+
 == Contribution
 
 === Fork

docs/modules/ROOT/examples/document-with-usage.adoc

@@ -0,0 +1,19 @@
+== Aliases
+
+=== hello
+[source, bash]
+----
+jbang hello <scriptOrFile>
+----
+
+[sidebar]
+Script that says hello back for each argument
+
+[source, bash]
+----
+This is a usage file, that will be rendered below the `hello` alias entry.
+
+!%$&@ So you want to use this script? !%$&@
+
+< Let me show you how you can use it. >
+----

docs/modules/ROOT/examples/hello.txt

@@ -0,0 +1,5 @@
+This is a usage file, that will be rendered below the `hello` alias entry.
+
+!%$&@ So you want to use this script? !%$&@
+
+< Let me show you how you can use it. >

jbang-catalog-document-generator-cli/src/main/java/org/rodnansol/commands/GenerateCommandPico.java

@@ -102,4 +102,10 @@ public void setHeaderAndFooterDirectRender(boolean headerAndFooterDirectRender)
     public void setPreferredCatalogName(String preferredCatalogName) {
         super.setPreferredCatalogName(preferredCatalogName);
     }
+
+    @Override
+    @CommandLine.Option(names = {"-cus", "--collapsible-usage-section"}, description = "Defines if the usage section should be collapsible or not")
+    public void setCollapsibleUsageSection(boolean collapsibleUsageSection) {
+        super.setCollapsibleUsageSection(collapsibleUsageSection);
+    }
 }

jbang-catalog-document-generator-core/src/main/java/org/rodnansol/commands/GenerateCommand.java

@@ -33,6 +33,8 @@ public class GenerateCommand implements Runnable {
     private boolean headerAndFooterDirectRender = false;
     private String preferredCatalogName;
 
+    private boolean collapsibleUsageSection = false;
+
     public GenerateCommand(DocumentGenerationAction documentGenerationAction) {
         this.documentGenerationAction = documentGenerationAction;
     }
@@ -58,6 +60,7 @@ private DocumentCustomization setupDocumentCustomization() {
         documentCustomization.setIncludeGenerationDate(includeGenerationDate);
         documentCustomization.setHeaderAndFooterDirectRender(headerAndFooterDirectRender);
         documentCustomization.setPreferredCatalogName(preferredCatalogName);
+        documentCustomization.setCollapsibleUsageSection(collapsibleUsageSection);
         return documentCustomization;
     }
 
@@ -176,4 +179,12 @@ public String getPreferredCatalogName() {
     public void setPreferredCatalogName(String preferredCatalogName) {
         this.preferredCatalogName = preferredCatalogName;
     }
+
+    public boolean isCollapsibleUsageSection() {
+        return collapsibleUsageSection;
+    }
+
+    public void setCollapsibleUsageSection(boolean collapsibleUsageSection) {
+        this.collapsibleUsageSection = collapsibleUsageSection;
+    }
 }

jbang-catalog-document-generator-core/src/main/java/org/rodnansol/document/DocumentCustomization.java

@@ -85,6 +85,13 @@ public class DocumentCustomization {
      */
     private String preferredCatalogName;
 
+    /**
+     * Defines if the usage section should be collapsible or not.
+     *
+     * @since 0.2.0
+     */
+    private boolean collapsibleUsageSection = false;
+
     public boolean isEnableTableOfContents() {
         return enableTableOfContents;
     }
@@ -165,6 +172,14 @@ public void setPreferredCatalogName(String preferredCatalogName) {
         this.preferredCatalogName = preferredCatalogName;
     }
 
+    public boolean isCollapsibleUsageSection() {
+        return collapsibleUsageSection;
+    }
+
+    public void setCollapsibleUsageSection(boolean collapsibleUsageSection) {
+        this.collapsibleUsageSection = collapsibleUsageSection;
+    }
+
     @Override
     public String toString() {
         return new StringJoiner(", ", DocumentCustomization.class.getSimpleName() + "[", "]")
@@ -178,6 +193,7 @@ public String toString() {
             .add("includeGenerationDate=" + includeGenerationDate)
             .add("headerAndFooterDirectRender=" + headerAndFooterDirectRender)
             .add("preferredCatalogName='" + preferredCatalogName + "'")
+            .add("collapsibleUsageSection=" + collapsibleUsageSection)
             .toString();
     }
 }

jbang-catalog-document-generator-core/src/main/java/org/rodnansol/document/DocumentGenerationAction.java

@@ -62,7 +62,7 @@ public void parseJsonFileAndGenerateDocument(CreateDocumentCommand createDocumen
             }
             DocumentData documentData = getDocumentData(createDocumentCommand);
             generateDocument(createDocumentCommand.templateType().getTemplate(), documentData, createDocumentCommand.outputFile());
-            LOGGER.info("AsciiDoc documentation generated successfully to: [{}]", createDocumentCommand.outputFile().getAbsolutePath());
+            LOGGER.info("Documentation generated successfully to: [{}]", createDocumentCommand.outputFile().getAbsolutePath());
             updateChecksum(createDocumentCommand);
         } catch (IOException e) {
             throw new DocumentGenerationException("Error during creating document", e);

jbang-catalog-document-generator-core/src/main/java/org/rodnansol/document/DocumentGenerationProperties.java

@@ -0,0 +1,19 @@
+package org.rodnansol.document;
+
+import io.smallrye.config.ConfigMapping;
+
+/**
+ * Document generation properties.
+ *
+ * @author nandorholozsnyak
+ * @since 0.2.0
+ */
+@ConfigMapping(prefix = "app.document")
+public interface DocumentGenerationProperties {
+
+    /**
+     * Get the current working directory.
+     */
+    String currentWorkingDirectory();
+
+}

jbang-catalog-document-generator-core/src/main/java/org/rodnansol/handlebars/CustomUsageConstants.java

@@ -0,0 +1,15 @@
+package org.rodnansol.handlebars;
+
+/**
+ * Constants for the custom usage sections.
+ *
+ * @author nandorholozsnyak
+ * @since 0.2.0
+ */
+class CustomUsageConstants {
+
+    public static final String EXTENSION = ".txt";
+
+    private CustomUsageConstants(){}
+
+}

jbang-catalog-document-generator-core/src/main/java/org/rodnansol/handlebars/CustomUsageRenderHelper.java

@@ -0,0 +1,40 @@
+package org.rodnansol.handlebars;
+
+import com.github.jknack.handlebars.Helper;
+import com.github.jknack.handlebars.Options;
+import org.rodnansol.document.DocumentGenerationProperties;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+/**
+ * Helper that renders the file at the given path built by the current working directory and by the value of the context to the document.
+ * <p>
+ * Usage:
+ * {@code
+ * {{#render_custom_usage alias-name}}{{/render_custom_usage}}
+ * }
+ *
+ * @author nandorholozsnyak
+ * @since 0.2.0
+ */
+class CustomUsageRenderHelper implements Helper<String> {
+
+    private final DocumentGenerationProperties documentGenerationProperties;
+
+    public CustomUsageRenderHelper(DocumentGenerationProperties documentGenerationProperties) {
+        this.documentGenerationProperties = documentGenerationProperties;
+    }
+
+    @Override
+    public Object apply(String context, Options options) throws IOException {
+        byte[] bytes = Files.readAllBytes(Path.of(getPath(context)));
+        return new String(bytes, StandardCharsets.UTF_8);
+    }
+
+    private String getPath(String context) {
+        return documentGenerationProperties.currentWorkingDirectory() + "/" + context + CustomUsageConstants.EXTENSION;
+    }
+}

jbang-catalog-document-generator-core/src/main/java/org/rodnansol/handlebars/HandlebarsConfiguration.java

@@ -4,6 +4,7 @@
 import com.github.jknack.handlebars.io.ClassPathTemplateLoader;
 import jakarta.enterprise.context.ApplicationScoped;
 import jakarta.enterprise.inject.Produces;
+import org.rodnansol.document.DocumentGenerationProperties;
 
 /**
  * Handlebars configuration class.
@@ -17,8 +18,12 @@
 public class HandlebarsConfiguration {
 
     @Produces
-    public Handlebars handlebars() {
-        return new Handlebars().with(new ClassPathTemplateLoader(), new WorkingDirectoryAwareRecursiveFileTemplateLoader(".", WorkingDirectoryProvider.INSTANCE));
+    public Handlebars handlebars(DocumentGenerationProperties documentGenerationProperties,
+                                 WorkingDirectoryProvider workingDirectoryProvider) {
+        return new Handlebars()
+            .registerHelper("has_custom_usage", new HasCustomUsageHelper(documentGenerationProperties))
+            .registerHelper("render_custom_usage", new CustomUsageRenderHelper(documentGenerationProperties))
+            .with(new ClassPathTemplateLoader(), new WorkingDirectoryAwareRecursiveFileTemplateLoader(documentGenerationProperties.currentWorkingDirectory(), workingDirectoryProvider));
     }
 
 }

jbang-catalog-document-generator-core/src/main/java/org/rodnansol/handlebars/HasCustomUsageHelper.java

@@ -0,0 +1,39 @@
+package org.rodnansol.handlebars;
+
+import com.github.jknack.handlebars.Helper;
+import com.github.jknack.handlebars.Options;
+import org.rodnansol.document.DocumentGenerationProperties;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+/**
+ * Helper that checks if a file exits at the given path built by the current working directory and by the value of the context.
+ * <p>
+ * Usage:
+ * {@code
+ * {{# has_custom_usage alias-name}}
+ * {{/has_custom_usage}}
+ * }
+ *
+ * @author nandorholozsnyak
+ * @since 0.2.0
+ */
+class HasCustomUsageHelper implements Helper<String> {
+
+    private final DocumentGenerationProperties documentGenerationProperties;
+
+    public HasCustomUsageHelper(DocumentGenerationProperties documentGenerationProperties) {
+        this.documentGenerationProperties = documentGenerationProperties;
+    }
+
+    @Override
+    public Object apply(String context, Options options) throws IOException {
+        return Files.exists(Path.of(getPath(context))) ? options.fn(context) : options.inverse(context);
+    }
+
+    private String getPath(String context) {
+        return documentGenerationProperties.currentWorkingDirectory() + "/" + context + CustomUsageConstants.EXTENSION;
+    }
+}

jbang-catalog-document-generator-core/src/main/java/org/rodnansol/handlebars/WorkingDirectoryProvider.java

@@ -1,5 +1,8 @@
 package org.rodnansol.handlebars;
 
+import jakarta.enterprise.context.ApplicationScoped;
+import org.rodnansol.document.DocumentGenerationProperties;
+
 import java.nio.file.Path;
 import java.nio.file.Paths;
 
@@ -9,19 +12,22 @@
  * @author nandorholozsnyak
  * @since 0.1.0
  */
+@ApplicationScoped
 class WorkingDirectoryProvider {
 
-    public static final WorkingDirectoryProvider INSTANCE = new WorkingDirectoryProvider();
+    private final DocumentGenerationProperties documentGenerationProperties;
 
-    private WorkingDirectoryProvider(){}
+    public WorkingDirectoryProvider(DocumentGenerationProperties documentGenerationProperties){
+        this.documentGenerationProperties = documentGenerationProperties;
+    }
 
     /**
      * Returns the current working directory.
      *
      * @return current working directory.
      */
     public Path getCurrentWorkingDirectoryPath() {
-        return Paths.get(".").toAbsolutePath().normalize();
+        return Paths.get(documentGenerationProperties.currentWorkingDirectory()).toAbsolutePath().normalize();
     }
 
 }

jbang-catalog-document-generator-core/src/main/resources/application.properties

@@ -2,6 +2,8 @@
 %dev.quarkus.log.console.format=%d{yyyy-MM-dd HH:mm:ss} [%c{3.}] %s%e%n
 %dev.quarkus.console.color=true
 %dev.quarkus.log.console.darken=1
+%dev.app.document.current-working-directory=../jbang-catalog-document-generator-core/
+app.document.current-working-directory=.
 quarkus.banner.enabled=false
 quarkus.log.category."org.rodnansol".level=INFO
 quarkus.log.level=OFF