feat(core): Generate an empty file if the input file is missing (#68) (…

…#76)

* feat(core): Generate an empty file if the input file is missing (#68)

- Generate an empty file if the input file is missing
- Extra documentation about the failOnMissingInput
- gradle profile is always active
- pre-commit change
- latest-version change for release preparation

docs/modules/ROOT/pages/gradle-plugin.adoc

@@ -399,6 +399,12 @@ Or run them in two separate commands:
 |Empty list - Everything will be included
 |0.5.0
 
+|failOnMissingInput
+|Defines if the build should fail if the input file is missing/not existing.
+|Yes
+|
+|0.7.0
+
 |===
 ====
 
@@ -504,6 +510,12 @@ Or run them in two separate commands:
 |
 |0.5.0
 
+|failOnMissingInput
+|Defines if the build should fail if the input file is missing/not existing.
+|Yes
+|
+|0.7.0
+
 |===
 
 [#aggregation-input]

docs/modules/ROOT/pages/index.adoc

@@ -16,7 +16,7 @@ endif::[]
 :toc:
 :toc-placement!:
 :toclevels: 4
-:latest-version: 0.6.1
+:latest-version: 0.7.0
 
 [.text-center]
 image:https://img.shields.io/maven-central/v/org.rodnansol/spring-configuration-property-documenter.svg[Maven Central]

docs/modules/ROOT/pages/maven-plugin.adoc

@@ -374,6 +374,12 @@ As we can see in the `input` tags we can define an `input` field that can be:
 |Empty list - Everything will be included
 |0.4.0
 
+|failOnMissingInput
+|Defines if the build should fail if the input file is missing/not existing.
+|Yes
+|
+|0.7.0
+
 |===
 ====
 
@@ -479,6 +485,12 @@ As we can see in the `input` tags we can define an `input` field that can be:
 |
 |0.2.1
 
+|failOnMissingInput
+|Defines if the build should fail if any of the input files are missing/not existing.
+|Yes
+|
+|0.7.0
+
 |===
 
 [#aggregation-mojo-input]

docs/modules/ROOT/pages/migrations.adoc

@@ -1,5 +1,6 @@
 [#header]
 = Migrations
+
 ifndef::env-github[]
 :icons: font
 endif::[]
@@ -14,7 +15,106 @@ endif::[]
 :toc-placement!:
 :toclevels: 4
 
+[#version-0-7-0]
+== 0.6.0 -> 0.7.0
+
+Before the 0.7.0 version in case any of the input files during the `generate-and-aggregate-documents` Maven goal or `generateAndAggregateDocuments` Gradle task was missing the documentation was created but the missing elements were not rendered into the document, because there was nothing to be read.
+
+With the release of the 0.7.0 this changes and the build will fail, but it can be parametrized for both available goals/tasks.
+
+Maven goals:
+
+* generate-property-document
+* generate-and-aggregate-documents
+
+Gradle tasks:
+
+* generatePropertyDocument
+* generateAndAggregateDocuments
+
+=== Maven
+
+.pom.xml
+[source,xml]
+----
+<executions>
+    <execution>
+        <id>generate-adoc</id>
+        <phase>process-classes</phase>
+        <goals>
+            <goal>generate-property-document</goal>
+        </goals>
+        <configuration>
+            <type>TYPE</type>
+            <!--Set to true if the build should fail if the input file is missing, set to false if it should generate an empty document-->
+            <failOnMissingInput>true</failOnMissingInput>
+        </configuration>
+    </execution>
+    <execution>
+        <id>generate-adoc</id>
+        <phase>process-classes</phase>
+        <goals>
+            <goal>generate-and-aggregate-documents</goal>
+        </goals>
+        <configuration>
+            <type>TYPE</type>
+            <!--Set to true if the build should fail if the input file is missing, set to false if it should generate an empty document-->
+            <failOnMissingInput>true</failOnMissingInput>
+        </configuration>
+    </execution>
+</executions>
+----
+
+=== Gradle
+
+.gradle.build
+[source,groovy]
+----
+tasks.register('generateAdoc') {
+    dependsOn generatePropertyDocument {
+        failOnMissingInput = true // Will fail if input is missing
+        documentName = "Hello World"
+        type = "ADOC"
+        asciiDocCustomization {
+            contentCustomization {
+                includeEnvFormat = true
+                includeClass = false
+                includeDeprecation = false
+                includeDescription = false
+            }
+            unknownGroupLocalization = "Renamed unknown group"
+            tocLevels = 3
+        }
+    }
+}
+
+tasks.register('generateAdocFromMissingInputFile') {
+    dependsOn generatePropertyDocument {
+        failOnMissingInput = false // Won't fail if input is missing, and empty file will be made
+        metadataInput = new File("non-existing.json")
+        outputFile = new File("build/property-docs/non-existing-file.adoc")
+        documentName = "Hello World"
+        type = "ADOC"
+        asciiDocCustomization {
+            contentCustomization {
+                includeEnvFormat = true
+                includeClass = false
+                includeDeprecation = false
+                includeDescription = false
+            }
+            unknownGroupLocalization = "Renamed unknown group"
+            tocLevels = 3
+        }
+    }
+}
+----
+
+[#version-0-6-1]
+== 0.6.0 -> 0.6.1
 
+No changes required.
+
+[#version-0-6-0]
 == 0.5.1 -> 0.6.0
 
 === Including environment format
@@ -24,6 +124,7 @@ Header appearance in the tables are now customizable, and to make sure the envir
 A new level of configuration is introduced, it can be configured with the `contentCustomization` key in Maven and in Gradle.
 
 ==== Maven
+
 .Till 0.5.1
 [source,xml]
 ----
@@ -92,6 +193,7 @@ A new level of configuration is introduced, it can be configured with the `conte
 ----
 
 ==== Gradle
+
 .Till 0.5.1
 [source,groovy]
 ----
@@ -188,32 +290,52 @@ tasks.register('generateXml') {
 }
 ----
 
+[#version-0-5-1]
 == 0.5.0 -> 0.5.1
+
 No changes required.
 
+[#version-0-5-0]
 == 0.4.0 -> 0.5.0
+
 No changes required.
 
+[#version-0-4-0]
 == 0.3.0 -> 0.4.0
+
 No changes required.
 
+[#version-0-3-0]
 == 0.2.4 -> 0.3.0
+
 No changes required.
 
+[#version-0-2-4]
 == 0.2.3 -> 0.2.4
+
 No changes required.
 
+[#version-0-2-3]
 == 0.2.2 -> 0.2.3
+
 No changes required.
 
+[#version-0-2-2]
 == 0.2.1 -> 0.2.2
+
 No changes required.
 
+[#version-0-2-1]
 == 0.2.0 -> 0.2.1
+
 No changes required.
 
+[#version-0-2-0]
 == 0.1.1 -> 0.2.0
+
 No changes required.
 
+[#version-0-1-1]
 == 0.1.0 -> 0.1.1
+
 No changes required.

hooks/commit-msg

@@ -1,5 +1,10 @@
 #!/usr/bin/env bash
 
+if git rev-parse -q --verify MERGE_HEAD; then
+    echo "This is a merge commit, no checks are required"
+    exit 0
+fi
+
 # Create a regex for a conventional commit.
 convetional_commit_regex="^(release|build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z \-]+\))?!?: .+$"
 

hooks/pre-commit

@@ -1,4 +1,8 @@
 #!/usr/bin/env bash
 
-echo "Verifying project before committing"
-./mvnw clean verify
+if git rev-parse -q --verify MERGE_HEAD; then
+    echo "This is a merge commit, no builds are going to be executed."
+else
+    echo "Building project"
+    ./mvnw clean verify
+fi

samples/gradle/simple-gradle-project/build.gradle

@@ -42,6 +42,7 @@ tasks.named('test') {
 
 tasks.register('generateAdoc') {
     dependsOn generatePropertyDocument {
+        failOnMissingInput = true
         documentName = "Hello World"
         type = "ADOC"
         asciiDocCustomization {
@@ -86,3 +87,23 @@ tasks.register('generateXml') {
         }
     }
 }
+
+tasks.register('generateAdocFromMissingInputFile') {
+    dependsOn generatePropertyDocument {
+        failOnMissingInput = false
+        metadataInput = new File("non-existing.json")
+        outputFile = new File("build/property-docs/non-existing-file.adoc")
+        documentName = "Hello World"
+        type = "ADOC"
+        asciiDocCustomization {
+            contentCustomization {
+                includeEnvFormat = true
+                includeClass = false
+                includeDeprecation = false
+                includeDescription = false
+            }
+            unknownGroupLocalization = "Renamed unknown group"
+            tocLevels = 3
+        }
+    }
+}

samples/multi-module/multi-module-docs/pom.xml

@@ -61,6 +61,36 @@
                             </inputFiles>
                         </configuration>
                     </execution>
+                    <execution>
+                        <id>aggregate-docs-markdown-with-non-existing-sources</id>
+                        <goals>
+                            <goal>generate-and-aggregate-documents</goal>
+                        </goals>
+                        <phase>package</phase>
+                        <configuration>
+                            <type>MARKDOWN</type>
+                            <failOnMissingInput>false</failOnMissingInput>
+                            <inputs>
+                                <input>
+                                    <name>Multi Module A</name>
+                                    <description>Multi Module A properties with a folder input</description>
+                                    <input>../multi-module-non-existing-a</input>
+                                </input>
+                                <input>
+                                    <name>Multi Module B</name>
+                                    <description>Multi Module B properties with a folder input</description>
+                                    <input>../multi-module-non-existing-b</input>
+                                </input>
+                            </inputs>
+                            <markdownCustomization>
+                                <headerEnabled>false</headerEnabled>
+                                <contentCustomization>
+                                    <includeEnvFormat>true</includeEnvFormat>
+                                </contentCustomization>
+                            </markdownCustomization>
+                            <outputFile>target/aggregated-non-existing-sources-md.md</outputFile>
+                        </configuration>
+                    </execution>
                     <execution>
                         <id>aggregate-docs-markdown-with-spring-related-configurations</id>
                         <goals>
@@ -335,7 +365,7 @@
                                 </input>
                             </inputs>
                             <asciiDocCustomization>
-                                <compactMode>true</compactMode>
+                                <templateMode>COMPACT</templateMode>
                             </asciiDocCustomization>
                             <outputFile>target/compact-include-and-exclude-list-based-document.adoc</outputFile>
                         </configuration>

samples/pom.xml

@@ -12,7 +12,7 @@
         <module>single-module</module>
         <module>multi-module</module>
         <module>quarkus-spring-boot-single-module</module>
-        <module>kotlin-example</module>
+<!--        <module>kotlin-example</module>-->
     </modules>
 
     <dependencyManagement>

samples/single-module/pom.xml

@@ -78,7 +78,7 @@
                         <configuration>
                             <type>ADOC</type>
                             <asciiDocCustomization>
-                                <compactMode>true</compactMode>
+                                <templateMode>COMPACT</templateMode>
                             </asciiDocCustomization>
                             <outputFile>target/compact-mode.adoc</outputFile>
                         </configuration>
@@ -99,6 +99,18 @@
                             </asciiDocCustomization>
                         </configuration>
                     </execution>
+                    <execution>
+                        <id>generate-empty-output-file-because-input-file-is-missing</id>
+                        <phase>process-classes</phase>
+                        <goals>
+                            <goal>generate-property-document</goal>
+                        </goals>
+                        <configuration>
+                            <metadataInput>not-existing.json</metadataInput>
+                            <type>ADOC</type>
+                            <outputFile>target/not-existing-input-file.adoc</outputFile>
+                        </configuration>
+                    </execution>
                     <execution>
                         <id>generate-adoc-with-include-list</id>
                         <phase>process-classes</phase>
@@ -216,7 +228,7 @@
                         <configuration>
                             <type>MARKDOWN</type>
                             <markdownCustomization>
-                                <compactMode>true</compactMode>
+                                <templateMode>COMPACT</templateMode>
                             </markdownCustomization>
                             <outputFile>target/compact-mode.md</outputFile>
                         </configuration>
@@ -262,7 +274,7 @@
                         <configuration>
                             <type>HTML</type>
                             <htmlCustomization>
-                                <compactMode>true</compactMode>
+                                <templateMode>COMPACT</templateMode>
                             </htmlCustomization>
                             <outputFile>target/compact-mode.html</outputFile>
                         </configuration>