Test documentation links against a TOC file

lib/foreman_theme_satellite/documentation.rb

@@ -10,7 +10,7 @@ module Documentation
 
       # Managing Hosts
       'ForemanRemoteExecution' => "#{ForemanThemeSatellite.documentation_root}/managing_hosts/configuring_and_setting_up_remote_jobs_managing-hosts",
-      'ExecutingaJob' => "#{ForemanThemeSatellite.documentation_root}/managing_hosts/configuring_and_setting_up_remote_jobs_managing-hosts#configuring-the-global-smartproxy-remote-execution-setting_managing-hosts",
+      'ExecutingaJob' => "#{ForemanThemeSatellite.documentation_root}/managing_hosts/configuring_and_setting_up_remote_jobs_managing-hosts#Configuring_the_Global_capsule_Remote_Execution_Setting_in_satellite_managing-hosts",
       'JobTemplates' => "#{ForemanThemeSatellite.documentation_root}/managing_hosts/configuring_and_setting_up_remote_jobs_managing-hosts#setting-up-job-templates_managing-hosts",
       'ReportTemplates' => "#{ForemanThemeSatellite.documentation_root}/managing_hosts/using_report_templates_to_monitor_hosts_managing-hosts",
       'Reports' => "#{ForemanThemeSatellite.documentation_root}/managing_hosts/using_report_templates_to_monitor_hosts_managing-hosts",
@@ -58,17 +58,17 @@ module Documentation
       'Auditing' => "#{ForemanThemeSatellite.documentation_root}/satellite_overview_concepts_and_deployment_considerations/appe-architecture_guide-glossary_of_terms#varl-Glossary_of_Terms-Audits",
 
       # Install
-      'HTTP(S)Proxy' => "#{ForemanThemeSatellite.documentation_root}//installing_satellite_server_in_a_connected_network_environment/performing-additional-configuration#Configuring_Server_with_an_HTTP_Proxy_satellite",
+      'HTTP(S)Proxy' => "#{ForemanThemeSatellite.documentation_root}/installing_satellite_server_in_a_connected_network_environment/performing-additional-configuration#Configuring_Server_with_an_HTTP_Proxy_satellite",
 
       # Misc
       'GettingHelp' => "https://access.redhat.com/products/red-hat-satellite/#support",
 
       # Managing Security Compliance
-      'Monitoring_Compliance_security-compliance' => "#{ForemanThemeSatellite.documentation_root}/managing_security_compliance/Monitoring_Compliance_security-compliance",
-      'Managing_Compliance_Policies_security-compliance' => "#{ForemanThemeSatellite.documentation_root}/managing_security_compliance/Managing_Compliance_Policies_security-compliance",
-      'Configuring_SCAP_Contents_security-compliance' => "#{ForemanThemeSatellite.documentation_root}/managing_security_compliance/Configuring_SCAP_Contents_security-compliance",
-      'tailoring-xccdf-profiles_security-compliance' => "#{ForemanThemeSatellite.documentation_root}/managing_security_compliance/Configuring_SCAP_Contents_security-compliance#tailoring-xccdf-profiles_security-compliance",
-      'deploying-compliance-policies_security-compliance' => "#{ForemanThemeSatellite.documentation_root}/managing_security_compliance/Configuring_SCAP_Contents_security-compliance#deploying-compliance-policies_security-compliance",
+      'Monitoring_Compliance_security-compliance' => "#{ForemanThemeSatellite.documentation_root}/managing_security_compliance/monitoring_compliance_security-compliance",
+      'Managing_Compliance_Policies_security-compliance' => "#{ForemanThemeSatellite.documentation_root}/managing_security_compliance/managing_compliance_policies_security-compliance",
+      'Configuring_SCAP_Contents_security-compliance' => "#{ForemanThemeSatellite.documentation_root}/managing_security_compliance/configuring_scap_contents_security-compliance",
+      'tailoring-xccdf-profiles_security-compliance' => "#{ForemanThemeSatellite.documentation_root}/managing_security_compliance/configuring_scap_contents_security-compliance#tailoring-xccdf-profiles_security-compliance",
+      'deploying-compliance-policies_security-compliance' => "#{ForemanThemeSatellite.documentation_root}/managing_security_compliance/deploying-compliance-policies_security-compliance",
     }.freeze
 
     PLUGINS_DOCUMENTATION = {
@@ -77,7 +77,7 @@ module Documentation
     }.freeze
 
     SPECIAL_LINKS = [
-      [/docs\.theforeman\.org\/.*?\/Managing_Hosts\/.*?registering-a-host.*?managing-hosts/i, "#{ForemanThemeSatellite.documentation_root}/managing_hosts/registering_hosts_to_server_managing-hosts#Registering_Hosts_managing-hosts"],
+      [/docs\.theforeman\.org\/.*?\/Managing_Hosts\/.*?registering-a-host.*?managing-hosts/i, "#{ForemanThemeSatellite.documentation_root}/managing_hosts/registering_hosts_to_server_managing-hosts#Registering_Hosts_by_Using_Global_Registration_managing-hosts"],
     ]
   end
 end

lib/tasks/foreman_theme_satellite_tasks.rake

@@ -38,6 +38,34 @@ namespace :foreman_theme_satellite do
 
     Rake::Task['rubocop_foreman_theme_satellite'].invoke
   end
+
+  desc 'Validate documentation links against given TOC and FolderToLink files'
+  task :validate_docs do
+    toc_file = ENV['TOC']
+    abort "Please specify TOC=<toc_file>" unless toc_file
+
+    filename_to_link_file = ENV['F2L']
+    abort "Please specify F2L=<filename_to_link_file>" unless filename_to_link_file
+
+    require_relative '../../test/link_checker'
+    checker = LinksChecker.new(toc: toc_file, filename_to_link: filename_to_link_file)
+
+    require_relative '../foreman_theme_satellite/documentation'
+
+    failed = {}
+    all_links = ForemanThemeSatellite::Documentation::USER_GUIDE_DICTIONARY
+                .merge(ForemanThemeSatellite::Documentation::PLUGINS_DOCUMENTATION)
+                .merge(Hash[ForemanThemeSatellite::Documentation::SPECIAL_LINKS])
+
+    all_links.each do |key, doc_address|
+      next unless doc_address.match?(/html/)
+      failed[key] = doc_address unless checker.test_link(doc_address)
+    end
+
+    abort((failed.map { |key, doc_address| "FAILED: Cannot find #{doc_address} in TOC for entry: #{key}" } + ["Total failed: #{failed.count} entries"]).join("\n")) unless failed.empty?
+
+    puts "Successfully tested #{all_links.count} links"
+  end
 end
 
 Rake::Task[:test].enhance ['test:foreman_theme_satellite']

test/link_checker.rb

@@ -0,0 +1,61 @@
+require 'json'
+require 'uri'
+
+class LinksChecker
+  def initialize(toc:, filename_to_link:)
+    toc_source = JSON.parse(File.read(toc))
+    f2l = JSON.parse(File.read(filename_to_link))
+
+    @toc = fix_folder_titles(toc_source, f2l)
+  end
+
+  def fix_folder_titles(toc, f2l)
+    toc.transform_keys { |file| f2l[file] || file }
+  end
+
+  def test_link(url)
+    doc_path, anchor = decompose_link(url)
+
+    return false unless doc_path
+
+    anchors = navigate_path(doc_path)
+
+    return anchors unless anchor
+
+    anchors&.include?(anchor)
+  end
+
+  private
+
+  # Will decompose URL from https://localhost:3000/documentation/en-us/red_hat_satellite/6.15/html/managing_configurations_using_ansible_integration_in_red_hat_satellite/getting_started_with_ansible_in_satellite_ansible#Importing_Ansible_Roles_and_Variables_ansible
+  # to two parts:
+  # path: managing_configurations_using_ansible_integration_in_red_hat_satellite/getting_started_with_ansible_in_satellite_ansible
+  # chapter: Importing_Ansible_Roles_and_Variables_ansible
+  def decompose_link(link)
+    uri = URI.parse(link)
+
+    doc_path = extract_doc_path(uri.path)
+    anchor = uri.fragment
+
+    [doc_path, anchor]
+  end
+
+  def extract_doc_path(path)
+    # take the right part of the path after the '/html/' from the original link
+    %r{/html/(.*)}.match(path)&.[](1)
+  end
+
+  def navigate_path(path, hash = @toc)
+    return nil unless hash
+
+    split = path.match(%r{([^/]*)/(.*)})
+    first = split&.[](1) || path
+    rest = split&.[](2)
+
+    inner_hash = hash[first]
+
+    return inner_hash if rest.empty?
+
+    navigate_path(rest, inner_hash)
+  end
+end