From d5a1ccb7415c09525bb0b53b518999661dcf3cb1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aneta=20=C5=A0teflov=C3=A1=20Petrov=C3=A1?= Date: Fri, 3 Jul 2026 20:31:46 +0200 Subject: [PATCH 1/4] Add Vale rule for abstract character length validation Add AbstractLength.yml Vale rule to check that module abstracts are between 50 and 300 characters long. The rule uses a Tengo script to: - Find the [role="_abstract"] marker in AsciiDoc modules - Capture the abstract paragraph (single paragraph per module) - Count characters including text that spans multiple lines - Report errors with actual character count for clarity The script includes detailed comments explaining: - Import purposes and regex pattern breakdown - How the match array works and what each element contains - Why [\s\S] is used instead of . to match multi-line content - The one-abstract-per-module constraint Integrates with the foreman-documentation Vale style package. Co-Authored-By: Claude Sonnet 4.5 --- .../foreman-documentation/AbstractLength.yml | 51 +++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 .vale/styles/foreman-documentation/AbstractLength.yml diff --git a/.vale/styles/foreman-documentation/AbstractLength.yml b/.vale/styles/foreman-documentation/AbstractLength.yml new file mode 100644 index 00000000000..8bff0f73fc0 --- /dev/null +++ b/.vale/styles/foreman-documentation/AbstractLength.yml @@ -0,0 +1,51 @@ +# Check that abstract paragraphs are between 50 and 300 characters long. +--- +extends: script +message: "Abstract must be between 50 and 300 characters." +level: error +scope: raw +script: | + // Import required Tengo modules + text := import("text") // Text manipulation functions + fmt := import("fmt") // String formatting functions + + // Initialize empty array to store rule violations + matches := [] + + // Compile regex to find the abstract paragraph in AsciiDoc + // Each module contains exactly one abstract (a single paragraph following [role="_abstract"]) + // Pattern breakdown: + // \[role="_abstract"\] - Matches the abstract role marker + // \s*\n - Matches optional whitespace and newline after marker + // ([\s\S]+?) - Captures the abstract paragraph (non-greedy, including newlines) + // \n\n - Matches double newline (blank line) that ends paragraph + // Note: Using [\s\S] instead of . to match across multiple lines + abstract_regex := text.re_compile(`\[role="_abstract"\]\s*\n([\s\S]+?)\n\n`) + + // Find the abstract (there's only one per module) + // scope = the full document text being checked + // 1 = find only first match (since there's only one abstract per module) + result := abstract_regex.find(scope, 1) + + // Check if an abstract was found (find returns undefined if no match) + if result != undefined && len(result) > 0 && len(result[0]) > 1 { + // result[0][0] = full match including [role="_abstract"] marker + // result[0][1] = captured group (just the abstract paragraph text) + abstract_text := result[0][1].text + + // Count characters in the abstract + char_count := len(abstract_text) + + // Check if character count is outside valid range (50-300) + if char_count < 50 || char_count > 300 { + // Build custom error message with actual character count + msg := fmt.sprintf("Abstract must be between 50 and 300 characters (currently %d characters).", char_count) + + // Add this violation to the matches array + matches = append(matches, { + begin: result[0][1].begin, // Start position of abstract paragraph + end: result[0][1].end, // End position of abstract paragraph + message: msg // Custom error message with character count + }) + } + } From 1e7a772eb899d07dfc8a9a9cbc73a9966ea80717 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aneta=20=C5=A0teflov=C3=A1=20Petrov=C3=A1?= Date: Fri, 3 Jul 2026 20:49:59 +0200 Subject: [PATCH 2/4] Add hint on a fix --- .vale/styles/foreman-documentation/AbstractLength.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.vale/styles/foreman-documentation/AbstractLength.yml b/.vale/styles/foreman-documentation/AbstractLength.yml index 8bff0f73fc0..b16870afbe6 100644 --- a/.vale/styles/foreman-documentation/AbstractLength.yml +++ b/.vale/styles/foreman-documentation/AbstractLength.yml @@ -1,7 +1,7 @@ # Check that abstract paragraphs are between 50 and 300 characters long. --- extends: script -message: "Abstract must be between 50 and 300 characters." +message: "Abstract must be between 50 and 300 characters. Place any information that exceeds 300 characters in a new paragraph or paragraphs. It cannot be part of the abstract." level: error scope: raw script: | From 834995e4b228ab1f573858b24a115d45945ab037 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aneta=20=C5=A0teflov=C3=A1=20Petrov=C3=A1?= Date: Fri, 3 Jul 2026 20:57:46 +0200 Subject: [PATCH 3/4] Test abstract length violations --- guides/common/modules/con_content-flow-in-project.adoc | 2 ++ .../modules/con_how-puppet-integrates-with-project.adoc | 1 + guides/common/modules/proc_creating-a-webhook.adoc | 1 + guides/common/modules/proc_renaming-server.adoc | 5 +++++ 4 files changed, 9 insertions(+) diff --git a/guides/common/modules/con_content-flow-in-project.adoc b/guides/common/modules/con_content-flow-in-project.adoc index a9d498945e8..9ced0115c9b 100644 --- a/guides/common/modules/con_content-flow-in-project.adoc +++ b/guides/common/modules/con_content-flow-in-project.adoc @@ -4,6 +4,8 @@ = Content flow in {ProjectName} [role="_abstract"] +Test short abstract. + Content flow in {ProjectName} involves management and distribution of content from external sources to hosts. Content in {Project} flows from _external content sources_ to _{ProjectServer}_. diff --git a/guides/common/modules/con_how-puppet-integrates-with-project.adoc b/guides/common/modules/con_how-puppet-integrates-with-project.adoc index 60a9e7acfd2..80040ef60b1 100644 --- a/guides/common/modules/con_how-puppet-integrates-with-project.adoc +++ b/guides/common/modules/con_how-puppet-integrates-with-project.adoc @@ -7,6 +7,7 @@ Puppet uses a server-agent architecture. OpenVox server communicates with OpenVox agents on hosts registered to {Project} to manage the Puppet configuration of these hosts. {Project} components integrate with that architecture to provide configuration management capabilities in {Project}. +Test a very long abstract. Puppet architecture in {Project} comprises the following components: diff --git a/guides/common/modules/proc_creating-a-webhook.adoc b/guides/common/modules/proc_creating-a-webhook.adoc index 30a0eab4a79..13564b85049 100644 --- a/guides/common/modules/proc_creating-a-webhook.adoc +++ b/guides/common/modules/proc_creating-a-webhook.adoc @@ -5,6 +5,7 @@ [role="_abstract"] When creating a webhook in the {ProjectWebUI}, you can customize events, payloads, HTTP authentication, content type, and headers. +This abstract is just the right length. ifndef::foreman-deb,orcharhino[] [NOTE] diff --git a/guides/common/modules/proc_renaming-server.adoc b/guides/common/modules/proc_renaming-server.adoc index 2971d94ca88..086abc5e0e3 100644 --- a/guides/common/modules/proc_renaming-server.adoc +++ b/guides/common/modules/proc_renaming-server.adoc @@ -4,8 +4,13 @@ = Renaming {ProjectServer} [role="_abstract"] +ifdef::satellite[] Rename {ProjectServer} when its hostname or domain changes so that components, {SmartProxyServers}, and registered hosts continue to communicate correctly. Use the `{project-change-hostname}` script and update all references to the new hostname. +endif::[] +ifndef::satellite[] +Test abstract with two build-specific variants that is too long as a whole. +endif::[] [WARNING] ==== From b79f84171ba529df5a362a857ce0d1866c08b1b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aneta=20=C5=A0teflov=C3=A1=20Petrov=C3=A1?= Date: Wed, 8 Jul 2026 15:08:04 +0200 Subject: [PATCH 4/4] Revert "Test abstract length violations" This reverts commit 834995e4b228ab1f573858b24a115d45945ab037. --- guides/common/modules/con_content-flow-in-project.adoc | 2 -- .../modules/con_how-puppet-integrates-with-project.adoc | 1 - guides/common/modules/proc_creating-a-webhook.adoc | 1 - guides/common/modules/proc_renaming-server.adoc | 5 ----- 4 files changed, 9 deletions(-) diff --git a/guides/common/modules/con_content-flow-in-project.adoc b/guides/common/modules/con_content-flow-in-project.adoc index 9ced0115c9b..a9d498945e8 100644 --- a/guides/common/modules/con_content-flow-in-project.adoc +++ b/guides/common/modules/con_content-flow-in-project.adoc @@ -4,8 +4,6 @@ = Content flow in {ProjectName} [role="_abstract"] -Test short abstract. - Content flow in {ProjectName} involves management and distribution of content from external sources to hosts. Content in {Project} flows from _external content sources_ to _{ProjectServer}_. diff --git a/guides/common/modules/con_how-puppet-integrates-with-project.adoc b/guides/common/modules/con_how-puppet-integrates-with-project.adoc index 80040ef60b1..60a9e7acfd2 100644 --- a/guides/common/modules/con_how-puppet-integrates-with-project.adoc +++ b/guides/common/modules/con_how-puppet-integrates-with-project.adoc @@ -7,7 +7,6 @@ Puppet uses a server-agent architecture. OpenVox server communicates with OpenVox agents on hosts registered to {Project} to manage the Puppet configuration of these hosts. {Project} components integrate with that architecture to provide configuration management capabilities in {Project}. -Test a very long abstract. Puppet architecture in {Project} comprises the following components: diff --git a/guides/common/modules/proc_creating-a-webhook.adoc b/guides/common/modules/proc_creating-a-webhook.adoc index 13564b85049..30a0eab4a79 100644 --- a/guides/common/modules/proc_creating-a-webhook.adoc +++ b/guides/common/modules/proc_creating-a-webhook.adoc @@ -5,7 +5,6 @@ [role="_abstract"] When creating a webhook in the {ProjectWebUI}, you can customize events, payloads, HTTP authentication, content type, and headers. -This abstract is just the right length. ifndef::foreman-deb,orcharhino[] [NOTE] diff --git a/guides/common/modules/proc_renaming-server.adoc b/guides/common/modules/proc_renaming-server.adoc index 086abc5e0e3..2971d94ca88 100644 --- a/guides/common/modules/proc_renaming-server.adoc +++ b/guides/common/modules/proc_renaming-server.adoc @@ -4,13 +4,8 @@ = Renaming {ProjectServer} [role="_abstract"] -ifdef::satellite[] Rename {ProjectServer} when its hostname or domain changes so that components, {SmartProxyServers}, and registered hosts continue to communicate correctly. Use the `{project-change-hostname}` script and update all references to the new hostname. -endif::[] -ifndef::satellite[] -Test abstract with two build-specific variants that is too long as a whole. -endif::[] [WARNING] ====