Skip to content

CI asciidoc/metanorma label headers check - #634

Open
fmigneault wants to merge 8 commits into
opengeospatial:masterfrom
crim-ca:ci-doc-headers
Open

fmigneault wants to merge 8 commits into
opengeospatial:masterfrom
crim-ca:ci-doc-headers

Conversation

@fmigneault

@fmigneault fmigneault commented Sep 17, 2026 •

Copy link
Copy Markdown
Member

Changes

This adds a CI script that will validate whether header/req/rec/per/table/section labels are provided, and whether their names are consistent across sections. Adding the labels ensures that we don't get floating UUID auto-generated in the HTML which cannot be referenced consistently between builds.

The script generates an output such as the following. When labels naming is inconsistent (e.g., switching prefixes, mix of -/_ not following usual pattern), it will also propose/explain what's wrong about them. It will also detect duplicates within respective core/extension documents to avoid the creation of wrong links (for example, found duplicate ats_dismiss_job-dismiss-success, one of which supposed to be ats_dismiss_job-dismiss-status).

With the CI integration, it will ensure that any edited AsciiDoc did not forget to include an anchor label, and that those provided are aligned with the type of contents contained (eg: req_... for a [requirement]).

> python .github/scripts/check_adoc_labels.py
The following section headers and/or normative blocks are missing a valid anchor label ([[label]]):

Status Label   Type  Line Name                               File / Problem
---------------------------------------------------------------------------
FAIL   MISSING Table 92   Conformance class URIs             core/sections/clause_2_conformance.adoc
FAIL   MISSING Table 6    (no title found)                   extensions/deploy_replace_undeploy/standard/sections/annex_history.adoc
FAIL   MISSING Table 20   (no title found)                   extensions/deploy_replace_undeploy/standard/sections/clause_0_front_material.adoc
FAIL   MISSING Table 26   Supported HTTP methods by resource extensions/deploy_replace_undeploy/standard/sections/clause_1_scope.adoc
FAIL   MISSING Table 6    (no title found)                   extensions/job_management/standard/sections/annex_history.adoc

Fixes

Using it, I fixed the >1100 cases that were missing or had an invalid anchor.
(see full list: https://github.com/opengeospatial/ogcapi-processes/actions/runs/35188120084/job/105094495456?pr=634)

I also identified and fixed the following notable cases that were inconsistent:

  • core/abstract_tests/core/ATS_test-process.adoc — [requirement] → [abstract_test]
  • extensions/deploy_replace_undeploy/standard/abstract_tests/dru/ATS_mutable-process.adoc — [requirement] → [abstract_test]
  • extensions/deploy_replace_undeploy/standard/abstract_tests/dru/ATS_test-process.adoc — [requirement] → [abstract_test]
  • extensions/job_management/standard/recommendations/job-management/update/PER_put-op.adoc — [requirement] → [permission], identifier /req/job-management/update-put-op → /per/job-management/update-put-op (no other references found)
  • core/recommendations/collection-output/PER_collection-output_response-response-one.adoc — typo pre_ → per_
  • core/recommendations/ogc-process-description/PER_extend-data-access-apis-values.adoc — typo pre_ → per_
  • core/recommendations/ogc-process-description/PER_value-passing.adoc — typo pre_ → per_

In Core, I replaced the response-response-[one|many] by response-output-[one|many] because the distinctive one/many is the selected output(s), so double response was confusing and misleading.

Finally, I patched the JSON contents that were missing wrapping {} as it made linters go wild. Beside the purposely partial definitions such as arrays with ..., they are now valid JSON contents.

Patch

Cherry-picked the commits from #607 that resolve the file reference for Part 3 CI build.
I suggest merging that PR first and resolve any conflict here after (if any).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant