From 5f9a17635a9754ec21db6939049b0a91c4173dfe Mon Sep 17 00:00:00 2001 From: Gerd Aschemann Date: Fri, 30 Aug 2024 16:58:17 +0200 Subject: [PATCH] #318 Add CLI documentation --- README.adoc | 2 + htmlSanityCheck-cli/README.adoc | 208 ++++++++++++++++++++++ htmlSanityCheck-gradle-plugin/README.adoc | 2 +- integration-test/common/build.gradle | 22 ++- src/docs/manual/01_cli.adoc | 10 ++ src/docs/manual/01_manual.adoc | 1 + 6 files changed, 242 insertions(+), 3 deletions(-) create mode 100644 htmlSanityCheck-cli/README.adoc create mode 100644 src/docs/manual/01_cli.adoc diff --git a/README.adoc b/README.adoc index 60544cbf..4ee4ff64 100644 --- a/README.adoc +++ b/README.adoc @@ -2,6 +2,7 @@ :doctype: book include::asciidoctor-config.ad[] +ifndef::xrefToCli[:xrefToCli: htmlSanityCheck-cli/README.adoc] ifndef::xrefToGradlePlugin[:xrefToGradlePlugin: htmlSanityCheck-gradle-plugin/README.adoc] [.lead] @@ -29,6 +30,7 @@ image:https://img.shields.io/github/issues/aim42/htmlSanityCheck.svg[link="https HSC can be currently used * As a xref:{xrefToGradlePlugin}#sec:usage[Gradle plugin], or +* As a xref:{xrefToCli}#sec:usage[Command Line Interface tool] (CLI), or * Programmatically from Java or other JVM languages (TBD). [NOTE] diff --git a/htmlSanityCheck-cli/README.adoc b/htmlSanityCheck-cli/README.adoc new file mode 100644 index 00000000..0abe3c5f --- /dev/null +++ b/htmlSanityCheck-cli/README.adoc @@ -0,0 +1,208 @@ += HSC CLI Module +:doctype: book +include::../asciidoctor-config.ad[] + +ifdef::env-github[] +:imagesdir: ../src/docs/images +endif::env-github[] +ifndef::xrefToManual[:xrefToManual: ../README.adoc] +:gradleProperties: link:../gradle.properties[] +ifdef::jbake-type[:gradleProperties: {project-url}/blob/develop/gradle.properties[]] + +The Command Line Interface (CLI) module of HTML Sanity Check (xref:{xrefToManual}[HSC]) enables to check generated or native HTML documentation from the command line. + +== Installation (Command Line Interface) + +=== Prerequisites + +* Java 8 or higher (`java` executable required on the OS search path (`${PATH} on Linux/macOS, `%path%` on Windows). + +=== Download + +Download the latest version of the HSC CLI from the https://github.com/aim42/htmlSanityCheck/releases[release page]. + +== Usage + +The CLI tool can be executed with the following command. +If the `sourceDirectory` is omitted, HSC uses the current directory as base-directory to search for HTML files. + +Linux / macOS:: ++ +[source,sh] +---- +hsc [ options ] [ sourceDirectory ] +---- + +Windows:: ++ +[source,powershell] +---- +hsc.bat [ options ] [ sourceDirectory ] +---- + +=== Options + +The CLI tool exposes a few options as part of its configuration: + +[horizontal] + (optional):: Directory where the HTML files are located. ++ +Type: Directory ++ +Default: Currrent directory (`.`) + +`--sourceDocuments` <...> (optional):: An override to process several source files, which must be a subset of all files available in `sourceDir`. ++ +Type: List of files ++ +Default: All files in `sourceDir` whose names end with `.html` + +`--checkingResultsDir` <...> (optional):: Directory where HSC writes the checking results. ++ +Type: Directory ++ +Default: `./reports/htmlSanityCheck/` + +`--junitResultsDir` <...> (optional):: Directory where HSC writes the results in JUnit XML format. +JUnit XML can be read by many tools, including CI environments. ++ +Type: Directory ++ +Default: `./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 milliseconds. ++ +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: ++ +[source,groovy] +.Checker Classes +---- +include::../htmlSanityCheck-core/src/main/java/org/aim42/htmlsanitycheck/check/AllCheckers.java[tag=checker-classes,indent=0] +---- + + +`--httpWarningCodes` (optional):: 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 contain the respective location. +==== + +`--httpErrorCodes` (optional):: 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):: 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`). +**** + +== Examples + +=== Basic Example + +[source,sh] +---- +java -jar htmlSanityCheck-cli-.jar --sourceDir ./docs +---- + +=== Extended Example + +[source,sh] +---- +java -jar htmlSanityCheck-cli-.jar \ + --sourceDir ./docs \ + --checkingResultsDir ./report/htmlchecks \ + --failOnErrors true \ + --httpConnectionTimeout 1000 \ + --checkerClasses DuplicateIdChecker,MissingImageFilesChecker +---- + +== Compatibility + +The CLI tool has been tested with the following Java versions: + +* Java 8 +* Java 11 +* Java 17 +* Java 21 + +== Development Versions + +In case you want to use a current development (or arbitrary branch or tag) version from GitHub, you can build the CLI tool from source. + +Clone the repository:: ++ +[source,sh] +---- +git clone https://github.com/aim42/htmlSanityCheck.git +cd htmlSanityCheck +---- + +Build the CLI tool:: ++ +[source,sh] +---- +./gradlew integrationTest +---- ++ +Gradle generates the application to `htmlSanityCheck-cli/build/install/hsc/`. diff --git a/htmlSanityCheck-gradle-plugin/README.adoc b/htmlSanityCheck-gradle-plugin/README.adoc index dce68b4b..380d683a 100644 --- a/htmlSanityCheck-gradle-plugin/README.adoc +++ b/htmlSanityCheck-gradle-plugin/README.adoc @@ -156,7 +156,7 @@ include::../htmlSanityCheck-core/src/main/java/org/aim42/htmlsanitycheck/tools/W .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. +Some HSC reports contain the respective location. ==== diff --git a/integration-test/common/build.gradle b/integration-test/common/build.gradle index 4ddc77e7..37665f9f 100644 --- a/integration-test/common/build.gradle +++ b/integration-test/common/build.gradle @@ -50,13 +50,31 @@ tasks.register('buildReadmeGradlePlugin', org.asciidoctor.gradle.jvm.Asciidoctor "imagesdir": "../images" ) } -buildReadmeGradlePlugin.dependsOn(buildReadmeRoot) +buildReadmeGradlePlugin.dependsOn(copyReadmeResources) +buildReadmeGradlePlugin.mustRunAfter(buildReadmeRoot) + +tasks.register('buildReadmeCli', org.asciidoctor.gradle.jvm.AsciidoctorTask) { + group 'Verification' + description 'Convert CLI README for integration test' + + sourceDir projectRoot + sources { + include 'htmlSanityCheck-cli/README.adoc' + } + baseDirFollowsSourceFile() + outputDir file("${Project.DEFAULT_BUILD_DIR_NAME}/docs") + attributes( + "imagesdir": "../images" + ) +} +buildReadmeCli.dependsOn(copyReadmeResources) +buildReadmeCli.mustRunAfter(buildReadmeGradlePlugin) tasks.register('buildReadmeAll') { group 'Verification' description 'Convert all READMEs for integration test' } -buildReadmeAll.dependsOn(buildReadmeRoot, buildReadmeGradlePlugin) +buildReadmeAll.dependsOn(buildReadmeRoot, buildReadmeGradlePlugin, buildReadmeCli) build.dependsOn(buildReadmeAll) /* diff --git a/src/docs/manual/01_cli.adoc b/src/docs/manual/01_cli.adoc new file mode 100644 index 00000000..3510748a --- /dev/null +++ b/src/docs/manual/01_cli.adoc @@ -0,0 +1,10 @@ +:filename: manual/01_cli.adoc +:imagesdir: ../images +:jbake-menu: Manual +:jbake-order: 20 +:jbake-title: HTML Sanity Check (CLI Tool) + +ifndef::projectRootDir[:projectRootDir: ../../..] +:xrefToManual: 01_manual.adoc + +include::{projectRootDir}/htmlSanityCheck-cli/README.adoc[leveloffset=+1] \ No newline at end of file diff --git a/src/docs/manual/01_manual.adoc b/src/docs/manual/01_manual.adoc index 57837191..e7d919b1 100644 --- a/src/docs/manual/01_manual.adoc +++ b/src/docs/manual/01_manual.adoc @@ -5,6 +5,7 @@ :jbake-title: HTML Sanity Check (Generic) ifndef::projectRootDir[:projectRootDir: ../../..] +:xrefToCli: 01_cli.adoc :xrefToGradlePlugin: 01_gradle-plugin.adoc include::{projectRootDir}/README.adoc[leveloffset=+1] \ No newline at end of file