diff --git a/README.adoc b/README.adoc index 1eed2259..59284994 100644 --- a/README.adoc +++ b/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 <> - -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]] -[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,7 +271,10 @@ 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 @@ -332,17 +282,23 @@ 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 diff --git a/asciidoctor-config.ad b/asciidoctor-config.ad new file mode 100644 index 00000000..760e2cec --- /dev/null +++ b/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 diff --git a/htmlSanityCheck-gradle-plugin/README.adoc b/htmlSanityCheck-gradle-plugin/README.adoc new file mode 100644 index 00000000..1a7a2dda --- /dev/null +++ b/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 <> + +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 <> +<2> Check out <> + +[[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 + diff --git a/integration-test/gradle-plugin/build.gradle b/integration-test/gradle-plugin/build.gradle index aefe5fcf..b8a1e2f6 100644 --- a/integration-test/gradle-plugin/build.gradle +++ b/integration-test/gradle-plugin/build.gradle @@ -7,8 +7,10 @@ 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' @@ -16,15 +18,26 @@ task copyResources(type: Copy) { } 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 @@ -32,7 +45,8 @@ htmlSanityCheck { 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. diff --git a/integration-test/gradle-plugin/src/test/resources/README.adoc b/integration-test/gradle-plugin/src/test/resources/README.adoc deleted file mode 120000 index 10c2628b..00000000 --- a/integration-test/gradle-plugin/src/test/resources/README.adoc +++ /dev/null @@ -1 +0,0 @@ -../../../../../README.adoc \ No newline at end of file diff --git a/integration-test/gradle-plugin/src/test/resources/config.ad b/integration-test/gradle-plugin/src/test/resources/config.ad new file mode 100644 index 00000000..1779202d --- /dev/null +++ b/integration-test/gradle-plugin/src/test/resources/config.ad @@ -0,0 +1 @@ +:hsc-url: https://github.com/aim42/htmlSanityCheck/[] \ No newline at end of file diff --git a/integration-test/gradle-plugin/src/test/resources/gradle.properties b/integration-test/gradle-plugin/src/test/resources/gradle.properties deleted file mode 120000 index d56d6616..00000000 --- a/integration-test/gradle-plugin/src/test/resources/gradle.properties +++ /dev/null @@ -1 +0,0 @@ -../../../../../gradle.properties \ No newline at end of file diff --git a/integration-test/gradle-plugin/src/test/resources/htmlsanitycheck-logo.png b/integration-test/gradle-plugin/src/test/resources/htmlsanitycheck-logo.png deleted file mode 120000 index 695f957e..00000000 --- a/integration-test/gradle-plugin/src/test/resources/htmlsanitycheck-logo.png +++ /dev/null @@ -1 +0,0 @@ -../../../../../htmlsanitycheck-logo.png \ No newline at end of file diff --git a/integration-test/gradle-plugin/src/test/resources/icon.png b/integration-test/gradle-plugin/src/test/resources/icon.png deleted file mode 120000 index 48838a1e..00000000 --- a/integration-test/gradle-plugin/src/test/resources/icon.png +++ /dev/null @@ -1 +0,0 @@ -../../../../../icon.png \ No newline at end of file diff --git a/integration-test/gradle-plugin/src/test/resources/integration-test.adoc b/integration-test/gradle-plugin/src/test/resources/integration-test.adoc index 045e4448..ea4b51e0 100644 --- a/integration-test/gradle-plugin/src/test/resources/integration-test.adoc +++ b/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/[] \ No newline at end of file +of {hsc-url} \ No newline at end of file diff --git a/integration-test/gradle-plugin/src/test/resources/sample-hsc-report.jpg b/integration-test/gradle-plugin/src/test/resources/sample-hsc-report.jpg deleted file mode 120000 index 8f88d62d..00000000 --- a/integration-test/gradle-plugin/src/test/resources/sample-hsc-report.jpg +++ /dev/null @@ -1 +0,0 @@ -../../../../../sample-hsc-report.jpg \ No newline at end of file diff --git a/integration-test/gradle-plugin/src/test/resources/structure101-logo.png b/integration-test/gradle-plugin/src/test/resources/structure101-logo.png deleted file mode 120000 index 1d087720..00000000 --- a/integration-test/gradle-plugin/src/test/resources/structure101-logo.png +++ /dev/null @@ -1 +0,0 @@ -../../../../../structure101-logo.png \ No newline at end of file