WIP 332 Fix and extend Gradle Plugin docs

aim42 · Aug 13, 2024 · 6b22902 · 6b22902
1 parent 702025d
commit 6b22902
Showing 1 changed file with 125 additions and 35 deletions.
diff --git a/htmlSanityCheck-gradle-plugin/README.adoc b/htmlSanityCheck-gradle-plugin/README.adoc
@@ -4,7 +4,7 @@ include::../asciidoctor-config.ad[]
 ifndef::xrefToManual[:xrefToManual: ../README.adoc]
 :gradleProperties: link:../gradle.properties[]
 ifdef::jbake-type[]
-:gradleProperties: {project-url}/gradle.properties[]
+:gradleProperties: {project-url}/blob/develop/gradle.properties[]
 endif::jbake-type[]
 
 = HSC Gradle Plugin
@@ -37,9 +37,9 @@ In case of https://docs.gradle.org/current/userguide/plugins.html#sec:old_plugin
 ----
 buildscript {
     repositories {
-        maven { url "{jitpack-url}" } // <1>
-        mavenCentral()
-        gradlePluginPortal() // <2>
+        // maven { url "{jitpack-url}" } // <1>
+        mavenCentral() // <2>
+        gradlePluginPortal() // <3>
     }
 
     dependencies {
@@ -49,14 +49,17 @@ buildscript {
 
 apply plugin: 'org.aim42.{project}'
 ----
-<1> In case you would like to use an older version (< 2.x) or a current development version, check out <<sec:other-versions>>
-<2> Check out <<box:current-version,current version>>
+<1> In case you would like to use a development version (or even branch), check out <<sec:development-versions,development versions>>.
+<2> Beginning with version `2.x` all releases will be published to https://central.sonatype.com/artifact/org.aim42.htmlSanityCheck/org.aim42.htmlSanityCheck.gradle.plugin[Maven Central].
+<3> The https://plugins.gradle.org[Gradle Plugin Portal] contains https://plugins.gradle.org/plugin/org.aim42.htmlSanityCheck[most versions] or will redirect downloads of newer versions to Maven Central.
+<4> Check out <<box:current-version,current version>>.
 
 [[box:current-version]]
 [IMPORTANT]
 .Latest (development) version
 ====
-The current development version is defined in {gradleProperties}
+// TODO differentiate between released/latest (from main branch) and develop(ment) versions as soon as current develop branch is merged to main
+The current (development) version is defined in {gradleProperties}
 
 [source]
 ----
@@ -72,47 +75,142 @@ The plugin adds a new task named `htmlSanityCheck`.
 This task exposes a few properties as part of its configuration:
 
 [horizontal]
-sourceDir:: (mandatory) directory where the html files are located.
-Type: File.
-Default: `build/docs`.
-sourceDocuments:: (optional) an override to process several source files, which may be a subset of all files available in `+{sourceDir}+`.
+`sourceDir` (mandatory):: Directory where the HTML files are located.
++
+Type: Directory.
+
+`sourceDocuments` (optional):: An override to process several source files, which may be a subset of all files available in `+{sourceDir}+`.
++
 Type: `org.gradle.api.file.FileCollection`.
-Defaults to all files in `+{sourceDir}+` whose names end with `.html`.
++
+Default: All files in `+{sourceDir}+` whose names end with `.html`.
 
-checkingResultsDir:: (optional) directory where the checking results written to.
-Defaults to `+{buildDir}+/reports/htmlSanityCheck/`
+`checkingResultsDir` (optional):: Directory where the checking results written to.
++
+Type: Directory.
++
+Default: `+{buildDir}+/reports/htmlSanityCheck/`
 
-junitResultsDir:: (optional) directory where the results are written to in JUnit XML format.
+`junitResultsDir` (optional):: Directory where the results are written to in JUnit XML format.
 JUnit XML can be read by many tools, including CI environments.
-Defaults to `+{buildDir}+/test-results/htmlchecks/`
++
+Type: Directory.
++
+Default: `+{buildDir}+/test-results/htmlchecks/`
+
+`failOnErrors` (optional):: Fail the build if any error was found in the checked pages.
++
+Type: Boolean.
++
+Default: `false`.
+
+`httpConnectionTimeout` (optional):: Timeout for http requests in ms.
++
+Type: Integer.
++
+Default: `5000`.
+
+`ignoreLocalHost` (optional):: Ignore localhost as hostname.
++
+Type: Boolean.
++
+Default: `false`.
+
+`ignoreIPAddresses` (optional):: Ignore IP addresses as hostname.
++
+Type: Boolean.
++
+Default: `false`.
+
+`checkerClasses` (optional):: The set of checker classes to be executed.
++
+Type: List.
++
+Default: All available checker classes.
++
+[source,groovy]
+.Checker Classes
+----
+include::../htmlSanityCheck-core/src/main/java/org/aim42/htmlsanitycheck/check/AllCheckers.java[tag=checker-classes,indent=0]
+----
 
-failOnErrors:: (optional) if set to "true", the build will fail if any error was found in the checked pages.
-Defaults to `false`
+`httpWarningCodes` (optional):: Additional HTTP response codes treated as warning.
++
+Type: List.
++
+Default:
++
+[source,groovy]
+----
+include::../htmlSanityCheck-core/src/main/java/org/aim42/htmlsanitycheck/tools/Web.java[tag=HTTP_WARNING_CODES,indent=0]
+// Redirects included
+include::../htmlSanityCheck-core/src/main/java/org/aim42/htmlsanitycheck/tools/Web.java[tag=HTTP_REDIRECT_CODES,indent=0]
+----
++
+
+[NOTE]
+.HTTP Redirects
+====
+Note that HTTP redirects are treated as a warning to make the user aware of the correct or new location (cf. {project-issues}/244[Issue 244]).
+Some HSC reports often contain the respective location.
+====
+
+
+
+`httpErrorCodes` (optional):: Additional HTTP response codes treated as error.
++
+Type: List.
++
+Default:
++
+[source,groovy]
+----
+include::../htmlSanityCheck-core/src/main/java/org/aim42/htmlsanitycheck/tools/Web.java[tag=HTTP_ERROR_CODES,indent=0]
+----
+
+`httpSuccessCodes` (optional):: Additional HTTP response codes treated as success.
++
+Type: List.
++
+Default:
++
+[source,groovy]
+----
+include::../htmlSanityCheck-core/src/main/java/org/aim42/htmlsanitycheck/tools/Web.java[tag=HTTP_SUCCESS_CODES,indent=0]
+----
+
+[[sidebar:http-response-codes]]
+.HTTP response code handling
+****
+The lists shown above are the default HTTP response codes handled by HSC.
+The mentioned configurations effectively move the configured codes around, i.e., if you add `308` to `httpErrorCodes` it is automatically removed from its default list (`httpWarningCodes`).
+****
 
-checkerClasses:: (optional) a set of checker classes to be executed.
-Defaults to all available checker classes.
 
 [[sec:examples]]
 == Examples
 
-.build.gradle (small example)
+=== Small Example
+`build.gradle`
 [source,groovy]
 ----
 apply plugin: 'org.aim42.htmlSanityCheck'
 
 htmlSanityCheck {
-    sourceDir = new File( "$buildDir/docs" )
+    sourceDir = file( "$buildDir/docs" )
 
     // where to put results of sanityChecks...
-    checkingResultsDir = new File( "$buildDir/report/htmlchecks" )
+    checkingResultsDir = file( "$buildDir/report/htmlchecks" )
 
     // fail build on errors?
     failOnErrors = true
 
 }
 ----
 
-.build.gradle (extensive example)
+=== Extended example
+
+.`build.gradle`
 [source,groovy,subs='attributes']
 ----
 
@@ -189,8 +287,8 @@ htmlSanityCheck {
     // where to put results of sanityChecks...
     checkingResultsDir = new File( checkingResultsPath )
 
-    // fail build on errors?
-    failOnErrors = false
+    // fail build on errors
+    failOnErrors = true
 
    // http connection timeout in milliseconds
     httpConnectionTimeout = 1000
@@ -217,16 +315,8 @@ htmlSanityCheck {
 ----
 
 
-[[sec:other-versions]]
-== Old and development versions
-
-[[sec:old-versions]]
-=== Old versions
-
-https://plugins.gradle.org/plugin/org.aim42.htmlSanityCheck[Old versions] (< `2.x`) are available from the {gradle-plugin-url} repository.
-
 [[sec:development-versions]]
-=== Development versions
+== Development versions
 
 In case you want to use a current development (or arbitrary branch or tag) version from GitHub,
 add the following to your `settings.gradle`: