update-docs: extract the list of Git project-specific manual pages

There are a couple of "manual pages" that are really not interesting to
regular Git users because they affect how to work _with the Git
project_, not how to work _with Git_.

It is somewhat unfortunate (and a clear lack of separation of concerns)
that these are included in what Git's home page calls the "Git
reference".

Note that this has not been the case for a long time! Only with
ea0e16d (docs: include SubmittingPatches, 2018-04-16) it changed,
adding a single Git project-specific file to the site.

Since that dam was broken, 44bf766 (index.rake: build
MyFirstContribution tutorial, 2019-08-14) and later db4e920 (docs:
render 'MyFirstObjectWalk', 2020-06-07) introduced _further_ pages that
have nothing to do, really, with how to use Git.

In preparation for labeling these pages clearly as specific to the Git
project, let's extract the list of these _special_ pages to a central
location where it can be reused in the Hugo part of the site generation.

Signed-off-by: Johannes Schindelin <[email protected]>

Author: dscho

data/docs_extra.yml

@@ -0,0 +1,6 @@
+---
+git_project_specific:
+  - MyFirstContribution
+  - MyFirstObjectWalk
+  - SubmittingPatches
+---

script/update-docs.rb

@@ -13,6 +13,7 @@
 SITE_ROOT = File.join(File.expand_path(File.dirname(__FILE__)), '../')
 DOCS_INDEX_FILE = "#{SITE_ROOT}external/docs/content/docs/_index.html"
 DATA_FILE = "#{SITE_ROOT}external/docs/data/docs.yml"
+DOCS_EXTRA_FILE = "#{SITE_ROOT}data/docs_extra.yml"
 
 def read_data
   if File.exist?(DATA_FILE)
@@ -29,6 +30,20 @@ def read_data
   data
 end
 
+def read_docs_extra
+  if File.exist?(DOCS_EXTRA_FILE)
+    # `permitted_classes` required to allow running with Ruby v3.1
+    docs_extra = YAML.load_file(DOCS_EXTRA_FILE)
+  else
+    docs_extra = {}
+  end
+
+  docs_extra.git_project_specific = [] unless docs_extra.git_project_specific
+
+  docs_extra
+end
+
+
 def make_asciidoc(content)
   Asciidoctor::Document.new(content,
                             attributes: {
@@ -286,6 +301,7 @@ def index_doc(filter_tags, doc_list, get_content)
   rebuild = ENV.fetch("REBUILD_DOC", nil)
   rerun = ENV["RERUN"] || rebuild || false
 
+  docs_extra = read_docs_extra
   data = read_data
 
   tags = filter_tags.call(rebuild).sort_by { |tag| Version.version_to_num(tag.first[1..]) }
@@ -307,9 +323,6 @@ def index_doc(filter_tags, doc_list, get_content)
     doc_files = tag_files.select do |ent|
       ent.first =~
         /^Documentation\/(
-          SubmittingPatches |
-          MyFirstContribution.txt |
-          MyFirstObjectWalk.txt |
           (
             git.* |
             everyday |
@@ -323,7 +336,8 @@ def index_doc(filter_tags, doc_list, get_content)
             pull.* |
             scalar |
             technical\/.*
-        )\.txt)$/x
+        )\.txt)$/x or
+	doc_extra.git_project_specific.include?(ent.first.sub(/^Documentation\/(.*)(\.txt|\.adoc)?$/, '\1'))
     end
 
     puts "Found #{doc_files.size} entries"