Add ability to generate TOC file for testing links

[ShimShtein]

• I am familiar with the contributing guidelines.

This commit adds the ability to generate a TOC file that can be used to test documentation links.
This is done in the theme PR: RedHatSatellite/foreman_theme_satellite#31

Please cherry-pick my commits into:

• Foreman 3.9/Katello 4.11 (planned Satellite 6.15)
• Foreman 3.8/Katello 4.10
• Foreman 3.7/Katello 4.9 (Satellite 6.14)
• Foreman 3.6/Katello 4.8
• Foreman 3.5/Katello 4.7 (Satellite 6.13; orcharhino 6.6)
• Foreman 3.4/Katello 4.6 (EL8 only)
• Foreman 3.3/Katello 4.5 on EL7 & EL8 (Satellite 6.12 on EL8 only; orcharhino 6.4/6.5 on EL8 only)
• Foreman 3.2/Katello 4.4 on EL7 & EL8
• Foreman 3.1/Katello 4.3 on EL7 & EL8 (Satellite 6.11 EL7/8; orcharhino 6.3 on EL7/8)
• We do not accept PRs for Foreman older than 3.1.

[github-actions]

The PR preview for f84f0e7 is available at theforeman-foreman-documentation-preview-pr-2665.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

[maximiliankolb]

Thanks for your contribution. @ShimShtein Can you please update your PR?

[ShimShtein]

Updated the PR, should be OK now.
@ekohl ,

What is this file for? It looks like it's converting files to Satellite file naming, but I don't understand the point. Wouldn't index-satellite.html be correct then?

This file translates book names into the first part of documentation link path. The translation is not trivial, so I can't actually use an algorithm to derive the book name from the link.

[ShimShtein]

@maximiliankolb ready for another round

[maximiliankolb]

Took me a little while to see that this only works for "foreman" as build target.

$ rm -fr guides/build && podman run --rm -v $(pwd):/foreman-documentation:Z tmp_review_2665 make toc
$ wc guides/build/toc.json
  931  1028 43851 guides/build/toc.json
$ cat guides/build/toc.json | jq -e
$ echo $?
0

I've built the container image based on your branch. I generally run rm -fr guides/build && podman run --rm -v $(pwd):/foreman-documentation:Z foreman_documentation make html BUILD=katello locally. With a build target, I get the following error message: scripts/extract_links_toc: warning: argument of top-level return is ignored and the JSON file is empty like {}.

two things: a) it would be nice to have a small section in guides/README.md how it works (maybe just copy my command?; maybe just say "run make toc"?) and why/when someone would want to do this.
b) it would be nice to make this work for all build targets, no?

I cannot comment on the ruby code tbh.

[ShimShtein]

Added a paragraph into the README file. It actually explained why running build targets other than foreman resulted in an empty TOC. To get something in the TOC, we will need to modify the upstream_filename_to_link.json file.

[ShimShtein]

@ekohl I think it's ready for another round.

[Lennonka]

I've left you corrections for folder names of Satellite guides in 6.15.
They have to be precise, otherwise we would be getting 404s.

FYI The guide titles/folder names may and do differ between Satellite releases!

[ShimShtein]

@Lennonka Ready for another round

[Lennonka]

A couple of suggestions.
I cannot comment on the ruby code.
The rest LGTM.

[maximiliankolb]

@ekohl Please have a look at the code.

[ShimShtein]

@ekohl Changed the files.

I'd prefer to make it explicit that this if for Satellite.

Would you like to call it upstream_filename_to_satellite_link ?

[ekohl]

Would you like to call it upstream_filename_to_satellite_link ?

Sounds good to me. Mostly raising it because we have 2 downstreams, so it's ambiguous. Satellite is explicit so 👍

[ShimShtein]

@ekohl renamed the file and left comments on your questions.

[ekohl]

Since you're already doing this for Satellite only, you can limit it to just index-satellite.html. And also use the shebang

Suggested change

	F2L=upstream_filename_to_satellite_link.json ruby scripts/extract_links_toc build/**/index-*.html > build/toc.json
	F2L=upstream_filename_to_satellite_link.json ./scripts/extract_links_toc build/**/index-satellite.html > build/toc.json

Then for the mapping file you can map File.dirname($filename). In the JSON you'll only have a mapping of directory names:

{
  "Administering_Project": "administering_red_hat_satellite"
}

Then you probably want to change the JSON filename to mention directory instead of filename.

[ShimShtein]

I prefer specifying the file names explicitly. Downstream the files and directories structure looks a bit different.

Once we unify the upstream and downstream - that would be an option.

[ekohl]

If this includes the version in the filename then we'll need to make sure that this is updated during Satellite version bumping.

[ShimShtein]

Yes, that would make sense. It will be detected on the first run of the tests against the new TOC, since the links to the next version will be missing.

[ShimShtein]

@ekohl updated to use the shebang.

[ekohl]

I instist you should only read index-satellite.html because that's the only relevant guide. And please also update that in the JSON file.

Suggested change

	F2L=upstream_filename_to_satellite_link.json ./scripts/extract_links_toc build/**/index-*.html > build/toc.json
	F2L=upstream_filename_to_satellite_link.json ./scripts/extract_links_toc build/**/index-satellite.html > build/toc.json

[ShimShtein]

@ekohl Finally got it working and even without the toc target on the internal layer

[ekohl]

I think this is the last part, otherwise 👍. Thanks for iterating on it because I now think we have the correct version.

[ekohl]

Suggested change

	For example `build/Administering_Project/index-foreman-el.html` would be translated to `.../administering_red_hat_satellite/...` path in the TOC.
	For example `build/Administering_Project/index-satellite.html` would be translated to `.../administering_red_hat_satellite/...` path in the TOC.

[ShimShtein]

@ekohl resolved the last issue.