Uploaded image for project: 'OpenNMS'
  1. OpenNMS
  2. NMS-13205

Antora Xref validation CI/CD pipeline

    XMLWordPrintable

    Details

    • Type: Epic
    • Status: Resolved (View Workflow)
    • Priority: Minor
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: None
    • Security Level: Default (Default Security Scheme)
    • Labels:
      None
    • Epic Name:
      Antora xref validation CI/CD pipeline
    • HB Backlog Status:
      NB

      Description

      Bonnie Robinson found a xref validator to verify if links are broken in Antora. We should add this to each project in CircleCI so we can find and fix link errors early.

      A sample output looks like this:

      NODE_PATH="$(npm -g root)" antora --generator @antora/xref-validator antora-playbook-local.yml
      Unresolved xrefs (grouped by origin):
      
      worktree: /Users/indigo/workbench/git/opennms/docs | component: horizon | version: 28.0.0-SNAPSHOT
        path: modules/deployment/pages/sentinel/introduction.adoc | xref: deployment/system-scalability/time-series-storage/newts.adoc
        path: modules/development/nav.adoc | xref: rest/maps.adoc
        path: modules/operation/pages/alarms/configuring-alarms.adoc | xref: events/anataomy-events.adoc
        path: modules/operation/pages/alarms/introduction.adoc | xref: bsb/introduction.adoc
        path: modules/operation/pages/application-perspective-monitoring/application-perspective-monitoring.adoc | xref: https://docs.opennms.org/opennms/releases/latest/guide-install/guide-install.html
        path: modules/operation/pages/meta-data.adoc | xref: https://docs.opennms.org/opennms/releases/latest/guide-development/guide-development.html
        path: modules/operation/pages/meta-data.adoc | xref: minion/ttl.adoc
        path: modules/operation/pages/performance-data-collection/collectors/http.adoc | xref: system-properties.adoc
        path: modules/operation/pages/performance-data-collection/collectors/xml.adoc | xref: system-properties.adoc
        path: modules/operation/pages/provisioning/getting-started.adoc | xref: integration.adoc
        path: modules/operation/pages/service-assurance/monitors/DhcpMonitor.adoc | xref: serivce-assurance/monitors/introduction.adoc
        path: modules/operation/pages/service-assurance/monitors/LdapsMonitor.adoc | xref: service-assurance/monitors/LdapMonitor.adOC
        path: modules/operation/pages/telemetryd/protocols/sflow.adoc | xref: flows/introduction.adco
      
      antora: xref validation failed! Found 13 unresolved xrefs. See previous report for details.
      

      we can see there are various link errors, because of typos which we wouldn't have found easily otherwise.

        Attachments

          Activity

            People

            Assignee:
            indigo Ronny Trommer
            Reporter:
            indigo Ronny Trommer
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Dates

              Created:
              Updated:
              Resolved:

                Git Integration