Write proper Maven site documentation on the latest Sentry Maven Skin (8.0.00) #113

Goal

Write proper end-user documentation on the Maven site and upgrade it to the latest Sentry Maven Skin (org.sentrysoftware.maven:sentry-maven-skin:8.0.00), matching the setup we landed in the Jawk project. Today the site is a single index.md on skin 6.4.01 with the legacy site descriptor; it should become a curated, multi-page documentation site published to GitHub Pages.

Current state

• src/site/site.xml uses the old SITE 1.x descriptor (root <project>, <bannerLeft><src>) and pins the skin to 6.4.01.
• Only one page exists: src/site/markdown/index.md.
• pom.xml has no maven-site-plugin configuration (inherited from the oss-parent POM) and a <reporting> section with only the PMD plugin.
• mvn clean verify site currently emits maven-project-info-reports-plugin:3.9.0 LinkageError: 'void org.apache.maven.doxia.sink.Sink.verbatim()' warnings — the inherited site plugin is too old for the report plugin. The maven-site-plugin 4.0.0-M16 bump below fixes this too.

Target (mirroring Jawk)

1. Skin + site tooling

• Migrate src/site/site.xml to the http://maven.apache.org/SITE/2.0.0 schema (root <site name="…">, <bannerLeft href="…"><image src="…"/></bannerLeft>).
• Upgrade the skin to:

  <skin>
    <groupId>org.sentrysoftware.maven</groupId>
    <artifactId>sentry-maven-skin</artifactId>
    <version>8.0.00</version>
  </skin>

• In pom.xml, pin the site plugin and add the skin-tools companion:

  <plugin>
    <artifactId>maven-site-plugin</artifactId>
    <version>4.0.0-M16</version>
    <dependencies>
      <dependency>
        <groupId>org.sentrysoftware.maven</groupId>
        <artifactId>maven-skin-tools</artifactId>
        <version>1.8.00</version>
      </dependency>
    </dependencies>
  </plugin>

• Use the skin's <custom> knobs: noDefaultLinks, keywords, a social/custom GitHub entry (fa-brands fa-github), and additionalLinks (Issue Tracker, Licenses, Releases).

2. Reporting section (populates the auto-generated <menu ref="reports"/>)

Add a <reporting> section like Jawk's: maven-project-info-reports-plugin:3.9.0 (summary, dependencies, dependency-info, scm, issue-management, licenses, plugins, team, ci-management, distribution-management), maven-jxr-plugin:3.6.0, maven-javadoc-plugin (javadoc report), maven-surefire-report-plugin:3.5.6, and the existing checkstyle / PMD / spotbugs reports.

3. Documentation pages (src/site/markdown/)

Replace the single page with a curated set, wired into grouped menus in site.xml. Proposed structure for a 2.0.0 WinRM client:

• Getting Started
  • index.md — overview, add the Maven dependency, minimal WQL example (refresh the existing one)
  • installation.md — coordinates, supported JDKs, no transitive CXF stack anymore
• Usage
  • wql.md — WinRMWqlExecutor.executeWql(...), namespaces, result shape, WqlQuerySyntaxException
  • commands.md — WinRMCommandExecutor.execute(...), stdout/stderr, exit codes, charset, working directory, file copy to shares
  • authentication.md — NTLM vs Kerberos (SPNEGO), domain\user, ticket cache, krb5.conf / -Djava.security.krb5.*
  • tls.md — HTTPS, validate-by-default, trust store, -Dorg.metricshub.winrm.tls.insecure=true
  • timeouts-and-errors.md — timeout semantics, the WinRMException/WSManFault surface
• Reference
  • migrating-from-1x.md — the 2.0.0 CXF removal, breaking changes, -Dorg.metricshub.winrm.backend=cxf now rejected (reuse the CHANGELOG/README upgrade notes)
  • Javadoc → apidocs/index.html
• <menu ref="reports" />

Adopt the Jawk page conventions: keywords: / description: front-matter and a MACRO{toc} per page. (winrm-java has no need for Jawk's Velocity .md.vm compatibility-data machinery — plain Markdown is enough.)

4. Site assets (src/site/resources/)

Reuse the existing favicon.ico, MetricsHub logo, and Poppins fonts already under src/site/resources/, or align site.css with Jawk's theming if we want visual consistency. Keep the MetricsHub banner/link colors.

5. Publish to GitHub Pages

Follow the Jawk model — do not add <distributionManagement><site>. Build with mvn verify site and publish target/site to GitHub Pages via actions/upload-pages-artifact + actions/deploy-pages (as Jawk's release.yml does), served at https://metricshub.org/winrm-java.

Acceptance criteria

• mvn clean verify site is green with no project-info-reports LinkageError warnings.
• The generated site uses the Sentry Maven Skin 8.0.00 with the curated menus above.
• Each documented feature (WQL, commands, authentication, TLS, 1.x→2.0 migration) has its own page, reachable from the menu.
• The reports menu (project info, Javadoc, JXR, surefire, checkstyle/PMD/spotbugs) is populated.
• The site is published to GitHub Pages on release.

Reference

Replicate the setup from jawk: src/site/site.xml (SITE 2.0 + skin 8.0.00), the maven-site-plugin 4.0.0-M16 + maven-skin-tools 1.8.00 config, the <reporting> section, and the GitHub Pages publish in .github/workflows/release.yml.