Add docs raketask to find the files to be deleted

Part of the Technical Writing team monthly tasks
(https://about.gitlab.com/handbook/engineering/ux/technical-writing/#regularly-scheduled-tasks)
is to find and delete the old redirect files (older than 3 months).

Doing this by hand was a tedious task, so this new raketask
aims to automate this.

doc/development/documentation/index.md

@@ -229,6 +229,7 @@ To add a redirect:
    ```markdown
    ---
    redirect_to: '../newpath/to/file/index.md'
+   remove_date: 'YYYY-MM-DD'
    ---
 
    This document was moved to [another location](../path/to/file/index.md).

doc/development/snowplow.md

 ---
 redirect_to: 'snowplow/index.md'
-remove_date: '2021-06-31'
+remove_date: '2021-06-30'
 ---
 This document was moved to [another location](snowplow/index.md).
 

lib/tasks/gitlab/docs/redirect.rake

 # frozen_string_literal: true
 require 'date'
 require 'pathname'
+require "yaml"
 
+#
 # https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page
+#
 namespace :gitlab do
   namespace :docs do
     desc 'GitLab | Docs | Create a doc redirect'
@@ -38,13 +41,14 @@ namespace :gitlab do
       # - If this is an external URL, move the date 1 year later.
       # - If this is a relative URL, move the date 3 months later.
       #
-      date = Time.now.utc.strftime('%Y-%m-%d')
-      date = new_path.start_with?('http') ? Date.parse(date) >> 12 : Date.parse(date) >> 3
+      today = Time.now.utc.to_date
+      date = new_path.start_with?('http') ? today >> 12 : today >> 3
 
       puts "=> Creating new redirect from #{old_path} to #{new_path}"
       File.open(old_path, 'w') do |post|
         post.puts '---'
         post.puts "redirect_to: '#{new_path}'"
+        post.puts "remove_date: '#{date}'"
         post.puts '---'
         post.puts
         post.puts "This file was moved to [another location](#{new_path})."
@@ -53,5 +57,69 @@ namespace :gitlab do
         post.puts "<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->"
       end
     end
+
+    desc 'GitLab | Docs | Clean up old redirects'
+    task :clean_redirects do
+      #
+      # Calculate new path from the redirect URL.
+      #
+      # If the redirect is not a full URL:
+      #   1. Create a new Pathname of the file
+      #   2. Use dirname to get all but the last component of the path
+      #   3. Join with the redirect_to entry
+      #   4. Substitute:
+      #      - '.md' => '.html'
+      #      - 'doc/' => '/ee/'
+      #
+      # If the redirect URL is a full URL pointing to the Docs site
+      # (cross-linking among the 4 products), remove the FQDN prefix:
+      #
+      #   From : https://docs.gitlab.com/ee/install/requirements.html
+      #   To   : /ee/install/requirements.html
+      #
+      def new_path(redirect, filename)
+        if !redirect.start_with?('http')
+          Pathname.new(filename).dirname.join(redirect).to_s.gsub(%r(\.md), '.html').gsub(%r(doc/), '/ee/')
+        elsif redirect.start_with?('https://docs.gitlab.com')
+          redirect.gsub('https://docs.gitlab.com', '')
+        else
+          redirect
+        end
+      end
+
+      today = Time.now.utc.to_date
+
+      #
+      # Find the files to be deleted.
+      # Exclude 'doc/development/documentation/index.md' because it
+      # contains an example of the YAML front matter.
+      #
+      files_to_be_deleted = `grep -Ir 'remove_date:' doc | grep -v doc/development/documentation/index.md | cut -d ":" -f 1`.split("\n")
+
+      #
+      # Iterate over the files to be deleted and print the needed
+      # YAML entries for the Docs site redirects.
+      #
+      files_to_be_deleted.each do |filename|
+        frontmatter = YAML.safe_load(File.read(filename))
+        remove_date = Date.parse(frontmatter['remove_date'])
+        old_path = filename.gsub(%r(\.md), '.html').gsub(%r(doc/), '/ee/')
+
+        #
+        # Check if the removal date is before today, and delete the file and
+        # print the content to be pasted in
+        # https://gitlab.com/gitlab-org/gitlab-docs/-/blob/master/content/_data/redirects.yaml.
+        # The remove_date of redirects.yaml should be nine months in the future.
+        # To not be confused with the remove_date of the Markdown page.
+        #
+        if remove_date < today
+          File.delete(filename) if File.exist?(filename)
+
+          puts "  - from: #{old_path}"
+          puts "    to: #{new_path(frontmatter['redirect_to'], filename)}"
+          puts "    remove_date: #{remove_date >> 9}"
+        end
+      end
+    end
   end
 end