Add IGNORE content type in pre-processing

[aneta-petrova]

What changes are you introducing?

• Removing the ASSEMBLY content type
• Extending the Vale workflow with a pre-processing step that injects the IGNORE content type into assembly files

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

Each assembly and module must include a content type definition to be evaluated by asciidoctor-dita-vale (https://github.com/jhradilek/asciidoctor-dita-vale/blob/af6c00940de1ce99994ddd1631aa18d35a7ff0a3/README.md?plain=1#L130). With this PR, I'm trying to avoid the need to include the IGNORE content type definition in assembly files by injecting the module type before the Vale check runs.

This saves us the need of adding two lines into 165 files that literally just say "ignore this file".

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Made with Claude but reviewed by myself to the best of my abilities 🙃

Contributor checklists

• I am okay with my commits getting squashed when you merge this PR.
• I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

• Foreman 3.19/Katello 4.21
• Foreman 3.18/Katello 4.20 (Satellite 6.19)
• Foreman 3.17/Katello 4.19
• Foreman 3.16/Katello 4.18 (Satellite 6.18; orcharhino 7.6, 7.7, and 7.8)
• Foreman 3.15/Katello 4.17
• Foreman 3.14/Katello 4.16 (Satellite 6.17; orcharhino 7.4; orcharhino 7.5)
• Foreman 3.13/Katello 4.15 (EL9 only)
• Foreman 3.12/Katello 4.14 (Satellite 6.16; orcharhino 7.2 on EL9 only; orcharhino 7.3)
• We do not accept PRs for Foreman older than 3.12.

[github-actions]

The PR preview for aae2a82 is available at theforeman-foreman-documentation-preview-pr-4879.surge.sh

No diff compared to the current base

show diff

[jafiala]

While I like this approach, won't it just silence the vale check but still present problems during the actual migration? Assemblies should be converted to DITA maps in the migration, and the migration workflow might be looking for :_mod-docs-content-type: ASSEMBLY for that conversion.

But I suppose that will also apply to the manual :_mod-docs-content-type: IGNORE approach.

So among the two approaches, I think this one is preferable.

No matter which path we choose, we should also add a note to Contributing.

[aneta-petrova]

While I like this approach, won't it just silence the vale check but still present problems during the actual migration? Assemblies should be converted to DITA maps in the migration, and the migration workflow might be looking for :_mod-docs-content-type: ASSEMBLY for that conversion.

I (vaguely) recall a conversation with the author of https://github.com/jhradilek/asciidoctor-dita-vale/ where he said that adding content types during pre-processing was a valid solution.

For the IGNORE type, I think it is safe. (It's not that any other Vale checks depend on IGNORE being present, it just disables all the checks.)

For the other content types, it might be more tricky, which is why I'm not suggesting to add those to pre-processing. However, a solution certainly exists -- we could add those content types during the downstream sync, or the migration team could implement similar pre-processing on their side.

But I suppose that will also apply to the manual :_mod-docs-content-type: IGNORE approach.

So among the two approaches, I think this one is preferable.

No matter which path we choose, we should also add a note to Contributing.

[aneta-petrova]

No matter which path we choose, we should also add a note to Contributing.

To be honest, I don't think that's necessary because CONTRIBUTING.md currently doesn't mention a content type for assemblies at all:

foreman-documentation/CONTRIBUTING.md

Lines 156 to 161 in d95c628

	Assemblies are kept at the top of the `common/` subdirectory:
	* [`assembly`](https://redhat-documentation.github.io/modular-docs/#forming-assemblies): Files starting with `assembly_` contain user stories and the modules required to accomplish those user stories.
	See the [assembly template](https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_ASSEMBLY_a-collection-of-modules.adoc).
	* In this repository, do not nest assemblies. This means that assemblies cannot contain includes of other assemblies. This guidance overrides the Modular documentation recommendations.
	* Do not include assemblies without leveloffset or with leveloffset of two or more in `master.adoc` files.

Unlike the other content types, which are mentioned below these lines.

For contributors, this IMHO doesn't represent anything they would need to actively be aware of -- the assembly files get ignored silently under the hood, which the best way to ignore something ;)

[maximiliankolb]

I left two comments & will reproduce the rest of the diff later locally.

[maximiliankolb]

I think that you can basically shorten this script to

find . -type f -name "assembly_*.adoc" | xargs sed --in-place "1iBLUB\n"

Replace "blub" with the attribute. Note that this does not work locally as expected because git reports a different diff because the assemblies already have the attribute set. So it works, but git diff shows a weird diff 🙃

[aneta-petrova]

The way the script is written is designed to avoid the need to modify the original files. That's why it creates copies in a temp directory.

Then there are also some extra bits for potential debugging purposes (warning messages, tracking file count), which could also be useful, especially if/when we add more content types to the mix later.

As I stated before, this PR was drafted by AI and AI is known to write more lines than are sometimes necessary 🙃 When I reviewed it, it seemed to make sense to make it more robust -- especially that part about copying the files to a temp directory rather than modifying them directly 🤷

[maximiliankolb]

reproduce the rest of the diff later locally.

fd -t f "assembly_" | xargs sed --in-place "/:_mod-docs-content-type: ASSEMBLY/,+1d" so anyone can quickly reproduce the changes on this PR once it's ready for final ACK.

[aneta-petrova]

once it's ready for final ACK.

I dropped the (now unnecessary) step to make the preprocessing script executable, and explained my reasoning for keeping the script a bit more robust than a sed command.

Then I also fixed the script to inject IGNORE rather than ASSEMBLY, which I totally missed before 🙈

To test the PR, I performed the following steps:

1. I ran the script on an assembly: /scripts/preprocess-vale-dita.sh guides/common/assembly_managing-organizations.adoc
2. I checked that the temporary assembly created by the script includes the IGNORE content type on its first line: cat .vale-temp/guides/common/assembly_managing-organizations.adoc
3. I ran the DITA Vale check on the temporary assembly: vale --config=.vale-dita.ini .vale-temp/guides/common/assembly_managing-organizations.adoc
4. Additionally, I checked that the GH workflow lint DITA includes running the pre-processing script: https://github.com/theforeman/foreman-documentation/actions/runs/26814218371/job/79051743435?pr=4879

Is this enough to check that it's working as intended? Am I missing anything?

[maximiliankolb]

Is this enough to check that it's working as intended?

Yes.

[aneta-petrova]

Now that I'm looking at it as a whole, should we just modify the Vale workflow to process only guides/common/modules rather than guides/common? If the point is to tell Vale to IGNORE the assembly files, should we just exclude them? Isn't that the best kind of ignoring?

[maximiliankolb]

should we just modify the Vale workflow to process only guides/common/modules rather than guides/common?

Yes, good call.

[aneta-petrova]

Let's explore that approach in #4893

[aneta-petrova]

#4893 seems to be a much simpler and the preferable way to resolve the ASSEMBLY errors. However, I'm keeping this PR open in draft state because it's worth revisiting in the future when/if we decide to move the other content types (the ones in module files, which remain mandatory) to pre-processing.