WIP 309 Rewrite README(s)

- Separate core and gradle plugin docs
- Generate docs for integration test directly from the project root

README.adoc

@@ -1,32 +1,22 @@
-= image:htmlsanitycheck-logo.png[Html-SC] Html Sanity Check
-:icons: font
-// Align version with ./gradle.properties file
-:version: 2.0.0
-
-:plugin-url: https://github.com/aim42/htmlSanityCheck
-:plugin-issues: https://github.com/aim42/htmlSanityCheck/issues
-
-:asciidoctor-gradle-plugin-url: https://github.com/asciidoctor/asciidoctor-gradle-plugin
-
-:asciidoc-url: https://asciidoctor.org
-:gradle-url: https://gradle.org/
-
-:gernotstarke: https://github.com/gernotstarke
-:project: htmlSanityCheck
-:project-url: https://github.com/aim42/htmlSanityCheck
-:project-issues: https://github.com/aim42/htmlSanityCheck/issues
-:project-bugs: https://github.com/aim42/htmlSanityCheck/issues?q=is%3Aopen+is%3Aissue+label%3Abug
-
-ifdef::env-github[:outfilesuffix: .adoc]
+= image:htmlsanitycheck-logo.png[HSC] Html Sanity Check (HSC)
+// ifndef::sourceDir[:sourcedir: .]
+include::asciidoctor-config.ad[]
 
+[.lead]
+====
 This project provides some basic sanity checking on html files.
 
 It can be helpful in case of html generated from, e.g., {asciidoc-url}[Asciidoctor],
 Markdown or other formats -- as converters usually don't check for missing images
 or broken links.
+====
+
+It can be currently used
+
+* Programmatically from Java (or other JVM languages), or
+* As a xref:htmlSanityCheck-gradle-plugin/README.adoc[Gradle plugin].
 
-It can be used as a Gradle plugin.
-Standalone Java and graphical UI are planned for future releases.
+Standalone Java (CLI) executable and a https://maven.apache.org[Apache Maven] Plugin are planned for future releases.
 
 image:https://img.shields.io/badge/License-ccsa4-green.svg[link="https://creativecommons.org/licenses/by-sa/4.0/"]
 image:https://github.com/aim42/htmlSanityCheck/actions/workflows/gradle-build.yml/badge.svg[]
@@ -35,49 +25,6 @@ image:https://jitpack.io/v/org.aim42.htmlSanityCheck/htmlSanityCheck.svg[alt='Ji
 
 == Installation
 
-Use the following snippet inside a Gradle build file:
-
-.build.gradle
-[source,groovy,subs="attributes"]
-----
-plugins {
-    id 'org.aim42.{project}' version '{version}' // <1>
-}
-----
-<1> Checkout <<box:current-version,current version>>
-
-OR
-
-.build.gradle
-[source,groovy,subs="attributes"]
-----
-buildscript {
-    repositories {
-        maven {
-              url "https://plugins.gradle.org/m2/"
-            }
-    }
-
-    dependencies {
-        classpath ('gradle.plugin.org.aim42:{project}:{version}') // <1>
-    }
-}
-
-apply plugin: 'org.aim42.{project}'
-----
-<1> Checkout <<box:current-version,current version>>
-
-[[box:current-version]]
-[IMPORTANT]
-.Latest (development) version
-====
-The current development version is defined in link:gradle.properties[]
-
-[source]
-----
-include::gradle.properties[tag=version]
-----
-====
 
 == Usage
 
@@ -89,16 +36,16 @@ This task exposes a few properties as part of its configuration:
 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 [x-]`${sourceDir}`.
+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 [x-]`${sourceDir}` whose names end with `.html`.
+Defaults to all files in `+{sourceDir}+` whose names end with `.html`.
 
 checkingResultsDir:: (optional) directory where the checking results written to.
-Defaults to `${buildDir}/reports/htmlSanityCheck/`
+Defaults to `+{buildDir}+/reports/htmlSanityCheck/`
 
 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/`
+Defaults to `+{buildDir}+/test-results/htmlchecks/`
 
 failOnErrors:: (optional) if set to "true", the build will fail if any error was found in the checked pages.
 Defaults to `false`
@@ -235,7 +182,7 @@ htmlSanityCheck {
 |===
 | The overall goal is to create neat and clear reports,
 showing eventual errors within HTML files - as shown in the adjoining figure.
-| image:sample-hsc-report.jpg[width="200",link="sample-hsc-report.jpg"
+| image:sample-hsc-report.jpg[width="200",link="{imagesdir}/sample-hsc-report.jpg"
 (click on thumbnail for details)]
 |===
 
@@ -324,25 +271,34 @@ This tiny piece rests on incredible groundwork:
 * Code for string similarity calculation by
 https://github.com/rrice/java-string-similarity[Ralph Rice].
 
-* Initial implementation, maintenance and documentation by {gernotstarke}[Gernot Starke].
+* Implementation, maintenance and documentation by
+* Current implementation, main
+** Initially: {gernotstarke}[Gernot Starke],
+** Currently: {gerdaschemann}[Gerd Aschemann] and several other contributors.
 
 == Development
 
 In case you want to check out, fork and/or contribute:
 The documentation is maintained using the awesome
 https://github.com/docToolchain/docToolchain[docToolchain], created by https://rdmueller.github.io/[@rdmueller].
 
-After checkout, you should execute:
-
-`git submodule update -i`
+The complete documentation can be build and checked
 
-to ensure that the docToolchain submodule is downloaded.
+[source,bash,subs="attributes+"]
+----
+./dtcw \
+  generateHtml \
+  generateSite \# <1>
+  htmlSanityCheck # <2>
+----
+<1> This does currently only work with a JDK 8.x (at least on MacOS)
+<2> The docToolchain `htmlSanityCheck` task uses a released version of HSC (not the current development version) by default.
 
 === Helpful Sources for Development
 
 Several sources provided help during development:
 
-* https://www.gradle.org/docs/current/userguide/custom_plugins.html[Gradle guide on writing custom plugins]
+* Gradle guide on https://www.gradle.org/docs/current/userguide/custom_plugins.html[writing custom plugins]
 * Of course, the https://jsoup.org/apidocs/[JSoup API documentation]
 
 == Similar Projects

asciidoctor-config.ad

@@ -0,0 +1,23 @@
+:icons: font
+:toc: left
+:imagesdir: .
+
+// :outfilesuffix: adoc
+
+// Align the version with ./gradle.properties file
+:version: 2.0.0
+
+:asciidoc-url: https://asciidoctor.org
+:asciidoctor-gradle-plugin-url: https://github.com/asciidoctor/asciidoctor-gradle-plugin
+:gerdaschemann: https://github.com/ascheman
+:gernotstarke: https://github.com/gernotstarke
+:gradle-plugin-url: https://plugins.gradle.org/
+:gradle-url: https://gradle.org/
+:jitpack-url: https://jitpack.io/
+:maven-url: https://maven.apache.org/
+:plugin-issues: https://github.com/aim42/htmlSanityCheck/issues
+:plugin-url: https://github.com/aim42/htmlSanityCheck
+:project-bugs: https://github.com/aim42/htmlSanityCheck/issues?q=is%3Aopen+is%3Aissue+label%3Abug
+:project-issues: https://github.com/aim42/htmlSanityCheck/issues
+:project-url: https://github.com/aim42/htmlSanityCheck
+:project: htmlSanityCheck

htmlSanityCheck-gradle-plugin/README.adoc

@@ -0,0 +1,88 @@
+:doctype: book
+include::../asciidoctor-config.ad[]
+
+= HSC Gradle Plugin
+
+The {gradle-url}[Gradle] plugin of HTML Sanity Check (xref:../README.adoc[HSC]) enables to check generated or native HTML documentation from the Gradle build.
+
+[[sec:installation]]
+== Installation (Gradle Plugin)
+
+=== Default Installation
+
+Use the following snippet inside a Gradle build file:
+
+.build.gradle
+[source,groovy,subs="attributes+"]
+----
+plugins {
+    id 'org.aim42.{project}' version '{version}' // <1>
+}
+----
+<1> Checkout <<box:current-version,current version>>
+
+And add the following to
+
+.settings.gradle
+[source,groovy,subs="attributes+"]
+----
+pluginManagement {
+    repositories {
+        maven { url "{jitpack-url}" } // <1>
+        mavenCentral()
+        gradlePluginPortal() // <2>
+    }
+}
+----
+
+=== Legacy Installation
+
+In case of https://docs.gradle.org/current/userguide/plugins.html#sec:old_plugin_application[legacy plugin usage]
+
+.build.gradle
+[source,groovy,subs="attributes+"]
+----
+buildscript {
+    repositories {
+        maven { url "{jitpack-url}" } // <1>
+        mavenCentral()
+        gradlePluginPortal() // <2>
+    }
+
+    dependencies {
+        classpath ('gradle.plugin.org.aim42:{project}:{version}') // <2>
+    }
+}
+
+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>>
+
+[[box:current-version]]
+[IMPORTANT]
+.Latest (development) version
+====
+The current development version is defined in link:../gradle.properties[]
+
+[source]
+----
+include::../gradle.properties[tag=version]
+----
+====
+
+== Usage
+
+== Example
+
+[[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
+

integration-test/gradle-plugin/build.gradle

@@ -7,32 +7,46 @@ repositories {
     mavenCentral()
 }
 
-task copyResources(type: Copy) {
-    from "src/test/resources"
+def projectRoot = "../.."
+def sourceDirectory = "src/test/resources"
+task copyReadmeResources(type: Copy) {
+    from projectRoot
     include '*.jpg'
     include '*.png'
     include '*.properties'
     into "build/docs"
 }
 
 asciidoctor {
-    sourceDir file("src/test/resources")
-    sources { include '*.adoc' }
+    sourceDir sourceDirectory
+    sources { include '**/*.adoc' }
+    baseDirFollowsSourceFile()
     outputDir file("build/docs")
 }
 
+task buildReadmeRoot(type: org.asciidoctor.gradle.jvm.AsciidoctorTask) {
+    sourceDir projectRoot
+    sources {
+        include 'README.adoc'
+        include 'htmlSanityCheck-gradle-plugin/README.adoc'
+    }
+    baseDirFollowsSourceFile()
+    outputDir file("build/docs")
+}
+buildReadmeRoot.dependsOn(copyReadmeResources)
+
 htmlSanityCheck {
     sourceDir file("build/docs")
 
-    // where to put results of sanityChecks...
     checkingResultsDir = file("build/reports")
     failOnErrors = true
 
     logger.quiet "HSC version: ${htmlSanityCheckVersion}"
     logger.quiet "HSC sourceDir: ${sourceDir.absolutePath}"
     logger.quiet "HSC checkingResultsDir: ${checkingResultsDir.absolutePath}"
 }
-htmlSanityCheck.dependsOn(copyResources, asciidoctor)
+htmlSanityCheck.dependsOn(asciidoctor)
+htmlSanityCheck.dependsOn(buildReadmeRoot)
 
 /*
  * Copyright Gerd Aschemann and aim42 contributors.

integration-test/gradle-plugin/src/test/resources/config.ad

@@ -0,0 +1 @@
+:hsc-url: https://github.com/aim42/htmlSanityCheck/[]

integration-test/gradle-plugin/src/test/resources/integration-test.adoc

@@ -1,3 +1,4 @@
 = Just a very simple (integration) test
+include::config.ad[]
 
-of https://github.com/aim42/htmlSanityCheck/[]
+of {hsc-url}