diff --git a/README.adoc b/README.adoc index 89f41510..1eed2259 100644 --- a/README.adoc +++ b/README.adoc @@ -1,4 +1,4 @@ -= image:./htmlsanitycheck-logo.png[Html-SC] Html Sanity Check += image:htmlsanitycheck-logo.png[Html-SC] Html Sanity Check :icons: font // Align version with ./gradle.properties file :version: 2.0.0 @@ -8,7 +8,7 @@ :asciidoctor-gradle-plugin-url: https://github.com/asciidoctor/asciidoctor-gradle-plugin -:asciidoc-url: http://asciidoctor.org +:asciidoc-url: https://asciidoctor.org :gradle-url: https://gradle.org/ :gernotstarke: https://github.com/gernotstarke @@ -21,13 +21,12 @@ ifdef::env-github[:outfilesuffix: .adoc] 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 +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 used as Gradle plugin. Standalone Java and graphical UI -are planned for future releases. - +It can be used as a Gradle plugin. +Standalone Java and graphical UI 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[] @@ -39,11 +38,10 @@ image:https://jitpack.io/v/org.aim42.htmlSanityCheck/htmlSanityCheck.svg[alt='Ji Use the following snippet inside a Gradle build file: .build.gradle -[source,groovy] -[subs="attributes"] +[source,groovy,subs="attributes"] ---- plugins { - id 'org.aim42.{project}' version '{version}' // <1> + id 'org.aim42.{project}' version '{version}' // <1> } ---- <1> Checkout <> @@ -51,8 +49,7 @@ plugins { OR .build.gradle -[source,groovy] -[subs="attributes"] +[source,groovy,subs="attributes"] ---- buildscript { repositories { @@ -89,24 +86,25 @@ 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 [x-]`${sourceDir}`. Type: `org.gradle.api.file.FileCollection`. - Defaults to all files in [x-]`${sourceDir}` whose names end with `.html`. +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}`. +Type: `org.gradle.api.file.FileCollection`. +Defaults to all files in [x-]`${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 written to in JUnit XML format. JUnit XML can be - read by many tools including CI environments. - Defaults to `${buildDir}/test-results/htmlchecks/` +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/` failOnErrors:: (optional) if set to "true", the build will fail if any error was found in the checked pages. - Defaults to `false` - -checkerClasses:: (optional) a set of checker classes to be executed. Defaults to all available checker classes. - +Defaults to `false` +checkerClasses:: (optional) a set of checker classes to be executed. +Defaults to all available checker classes. == Examples @@ -127,29 +125,25 @@ htmlSanityCheck { } ---- - .build.gradle (extensive example) -[source, groovy] +[source,groovy,subs='attributes'] ---- import org.aim42.htmlsanitycheck.check.* buildscript { repositories { - maven { - url "https://plugins.gradle.org/m2/" - } - jcenter() + mavenCentral() + // This is only necessary for older releases (< 2.00) + gradlePluginPortal() } } - plugins { - id 'org.aim42.htmlsanitycheck' version '1.1.1' + id 'org.aim42.htmlsanitycheck' version '{version}' id 'org.asciidoctor.convert' version '1.5.8' } - // ==== path definitions ===== // =========================== @@ -192,9 +186,7 @@ asciidoctor { apply plugin: 'org.aim42.htmlSanityCheck' - htmlSanityCheck { - // ensure asciidoctor->html runs first // and images are copied to build directory @@ -243,12 +235,10 @@ 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" - (click on thumbnail for details)] +| image:sample-hsc-report.jpg[width="200",link="sample-hsc-report.jpg" +(click on thumbnail for details)] |=== - - == Types of Sanity Checks === Broken Cross References (aka Broken Internal Links) @@ -268,34 +258,36 @@ In this example, the bookmark is _misspelled_. Use checkerClass _BrokenCrossReferencesChecker_. === Missing Images Files -Images, referenced in '400) and warnings (status 1xx or 3xx). -StatusCodes are configurable ranges (as some people might -want some content behind paywalls NOT to result in errors...) +The current version (derived from branch 1.0.0-RC-2) contains a simple implementation that identifies errors (status >400) and warnings (status `1xx` or `3xx`). + +StatusCodes are configurable ranges (as some people might want some content behind paywalls NOT to result in errors...) Localhost or numerical IP addresses are currently NOT marked as suspicious. @@ -304,84 +296,76 @@ Please comment in case you have additional requirements. Use checkerClass _BrokenHttpLinksChecker_. === Other types of external links -*planned*: ftp, ntp or other protocols are currently not checked, -but should... - +*planned*: ftp, ntp or other protocols are currently not checked, but should... == Technical Documentation -In addition to checking HTML, this project serves as an example for http://arc42.de[arc42]. -Please see our https://aim42.github.io/htmlSanityCheck/arc42/About-This-Docu.html[software architecture documentation]. +In addition to checking HTML, this project serves as an example for https://arc42.de[arc42]. +Please see our https://aim42.github.io/htmlSanityCheck/arc42/About-This-Docu.html[software architecture documentation]. == Fundamentals + This tiny piece rests on incredible groundwork: * https://jsoup.org[Jsoup HTML parser] and analysis toolkit - robust and easy-to-use. * IntelliJ IDEA - my (Gernot) best (programming) friend. -* Of course, Groovy, Gradle, JUnit and Spockframework. - +* Of course, Groovy, Gradle, JUnit and Spock framework. == Ideas and Origin * The plugin heavily relies on code provided by {gradle-url}[Gradle]. -* Inspiration on code organization, implementation and testing of the plugin -came from the {asciidoctor-gradle-plugin-url}[Asciidoctor-Gradle-Plugin] by [@AAlmiray]. +* Inspiration on code organization, implementation and testing of the plugin came from the {asciidoctor-gradle-plugin-url}[Asciidoctor-Gradle-Plugin] by [@AAlmiray]. * Code for string similarity calculation by - https://github.com/rrice/java-string-similarity[Ralph Rice]. +https://github.com/rrice/java-string-similarity[Ralph Rice]. * Initial implementation, maintenance and documentation by {gernotstarke}[Gernot Starke]. == Development -In case you want to checkout, fork and/or contribute: +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]. +https://github.com/docToolchain/docToolchain[docToolchain], created by https://rdmueller.github.io/[@rdmueller]. -After checkout you should execute: +After checkout, you should execute: `git submodule update -i` to ensure that the docToolchain submodule is downloaded. - === 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] -* The code4reference tutorial an Gradle custom plugins, -http://code4reference.com/2012/08/gradle-custom-plugin-part-1/[part 1] and -http://code4reference.com/2012/08/gradle-custom-plugin-part-2/[part 2]. * Of course, the https://jsoup.org/apidocs/[JSoup API documentation] == Similar Projects -* The https://github.com/rackerlabs/gradle-linkchecker-plugin[gradle-linkchecker-plugin] is an (open source) gradle plugin -which validates that all links in a local HTML file tree go out to other existing local files or remote web locations. +* The https://github.com/rackerlabs/gradle-linkchecker-plugin[gradle-linkchecker-plugin] is an (open source) Gradle plugin which validates that all links in a local HTML file tree go out to other existing local files or remote web locations. It creates a simple text file report and might be a complement to this `HtmlSanityChecker`. - -* https://bmuschko.com/blog/golang-with-gradle/[Benjamin Muschko] has created a (go-based) command-line tool -to check links, called https://github.com/bmuschko/link-verifier[link verifier] +* https://bmuschko.com/blog/golang-with-gradle/[Benjamin Muschko] has created a (Go-based) command-line tool to check links, called https://github.com/bmuschko/link-verifier[link verifier]. +* https://github.com/gjtorikian/html-proofer[html-proofer] is written in Ruby and provides different usage scenarios (programmatically, CLI, and Docker). +* https://github.com/wjdp/htmltest[htmltest] is also written in Go(Lang) and claims to be rapid compared to `html-proofer` (stay tuned; we have plans for HSC to run with Graal in a quick way). == Contributing + Please report {plugin-issues}[issues or suggestions]. -Want to improve the plugin: Fork our {plugin-url}[repository] and -send a pull request. +Want to improve the plugin: Fork our {plugin-url}[repository] and send a pull request. == Licence -Currently code is published under the Apache-2.0 licence, -documentation under Creative-Commons-Sharealike-4.0. -Some day I'll unify that :-) +Currently, code is published under the Apache-2.0 licence, documentation under Creative-Commons-Sharealike-4.0. +Some day we'll unify that :-) + +== Kudos + +Big thanx to image:./structure101-logo.png[alt='Structure-101',link="https://structure101.com"] for helping us analyze and restructure our code. -Big thanx to Structure-101 for helping us analyze and restructure our code... -image:./structure101-logo.png[link="https://structure101.com"] diff --git a/integration-test/gradle-plugin/build.gradle b/integration-test/gradle-plugin/build.gradle index be1a25bc..aefe5fcf 100644 --- a/integration-test/gradle-plugin/build.gradle +++ b/integration-test/gradle-plugin/build.gradle @@ -1,18 +1,28 @@ -/* - * This file was generated by the Gradle 'init' task. - * - * This is a general purpose Gradle build. - * To learn more about Gradle by exploring our Samples at https://docs.gradle.org/8.5/samples - * This project uses @Incubating APIs which are subject to change. - */ - plugins { - id('org.aim42.htmlSanityCheck').version("${htmlSanityCheckVersion}") - // version project.properties['htmlSanityCheck.version'] ?: "UNKNOWN" + id 'org.aim42.htmlSanityCheck' version "${htmlSanityCheckVersion}" + id 'org.asciidoctor.jvm.convert' version '4.0.2' +} + +repositories { + mavenCentral() +} + +task copyResources(type: Copy) { + from "src/test/resources" + include '*.jpg' + include '*.png' + include '*.properties' + into "build/docs" +} + +asciidoctor { + sourceDir file("src/test/resources") + sources { include '*.adoc' } + outputDir file("build/docs") } htmlSanityCheck { - sourceDir = file("src/test/resources") + sourceDir file("build/docs") // where to put results of sanityChecks... checkingResultsDir = file("build/reports") @@ -22,11 +32,7 @@ htmlSanityCheck { logger.quiet "HSC sourceDir: ${sourceDir.absolutePath}" logger.quiet "HSC checkingResultsDir: ${checkingResultsDir.absolutePath}" } - -tasks.register("clean", Delete) { - //noinspection GrDeprecatedAPIUsage - delete project.buildDir -} +htmlSanityCheck.dependsOn(copyResources, asciidoctor) /* * 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 new file mode 120000 index 00000000..10c2628b --- /dev/null +++ b/integration-test/gradle-plugin/src/test/resources/README.adoc @@ -0,0 +1 @@ +../../../../../README.adoc \ 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 new file mode 120000 index 00000000..d56d6616 --- /dev/null +++ b/integration-test/gradle-plugin/src/test/resources/gradle.properties @@ -0,0 +1 @@ +../../../../../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 new file mode 120000 index 00000000..695f957e --- /dev/null +++ b/integration-test/gradle-plugin/src/test/resources/htmlsanitycheck-logo.png @@ -0,0 +1 @@ +../../../../../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 new file mode 120000 index 00000000..48838a1e --- /dev/null +++ b/integration-test/gradle-plugin/src/test/resources/icon.png @@ -0,0 +1 @@ +../../../../../icon.png \ No newline at end of file diff --git a/integration-test/gradle-plugin/src/test/resources/integration-test.html b/integration-test/gradle-plugin/src/test/resources/integration-test.html deleted file mode 100644 index 90cc6a78..00000000 --- a/integration-test/gradle-plugin/src/test/resources/integration-test.html +++ /dev/null @@ -1,693 +0,0 @@ - - - - - - - -Just a very simple (integration) test - - - - - - - -
- -
- - - - \ 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 new file mode 120000 index 00000000..8f88d62d --- /dev/null +++ b/integration-test/gradle-plugin/src/test/resources/sample-hsc-report.jpg @@ -0,0 +1 @@ +../../../../../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 new file mode 120000 index 00000000..1d087720 --- /dev/null +++ b/integration-test/gradle-plugin/src/test/resources/structure101-logo.png @@ -0,0 +1 @@ +../../../../../structure101-logo.png \ No newline at end of file