Merge pull request #39093 from vikram-redhat/move_topic_maps

Moved topic map in main, updated builds and instructions

Author: vikram-redhat

_topic_map.yml renamed to _topic_maps/_topic_map.yml

@@ -22,6 +22,7 @@
 import time
 import yaml
 import requests
+import tempfile
 
 from aura import cli
 
@@ -151,9 +152,25 @@ def find_build_config_file():
     """
     Finds the build config file to use, as it might be _topic_map.yml or _build_cfg.yml
     """
-    config = os.path.abspath(os.path.join(CLONE_DIR, "_topic_map.yml"))
+
+    # updated 23rd Nov to support files in _topic_maps folder
+
+    # load everything from the _topic_maps folder
+    file_list = os.listdir(os.path.join(CLONE_DIR, "_topic_maps"))
+
+    # create a temp file combining all values from that folder
+    # don't delete it immediately, and give it a suffix of swp which makes it ignored by git
+    with tempfile.NamedTemporaryFile(dir=CLONE_DIR, delete=False, suffix=".swp") as tmp:
+        for f in file_list:
+            with open(os.path.join(CLONE_DIR, "_topic_maps", f), "rb") as infile:
+                tmp.write(infile.read())
+
+    config = os.path.abspath(tmp.name)
+    log.info(config)
+
+    # backup look for a single _topic_map in the cloned directory
     if not os.path.isfile(config):
-        config = os.path.abspath(os.path.join(CLONE_DIR, "_build_cfg.yml"))
+        config = os.path.abspath(os.path.join(CLONE_DIR, "_topic_map.yml"))
 
     return config
 

build.py

@@ -15,6 +15,7 @@
 import time
 import yaml
 import requests
+import tempfile
 
 from aura import cli
 
@@ -144,13 +145,28 @@ def find_build_config_file():
     """
     Finds the build config file to use, as it might be _topic_map.yml or _build_cfg.yml
     """
-    config = os.path.abspath(os.path.join(CLONE_DIR, "_topic_map.yml"))
+
+    # updated 23rd Nov to support files in _topic_maps folder
+
+    # load everything from the _topic_maps folder
+    file_list = os.listdir(os.path.join(CLONE_DIR, "_topic_maps"))
+
+    # create a temp file combining all values from that folder
+    # don't delete it immediately, and give it a suffix of swp which makes it ignored by git
+    with tempfile.NamedTemporaryFile(dir=CLONE_DIR, delete=False, suffix=".swp") as tmp:
+        for f in file_list:
+            with open(os.path.join(CLONE_DIR, "_topic_maps", f), "rb") as infile:
+                tmp.write(infile.read())
+
+    config = os.path.abspath(tmp.name)
+    log.info(config)
+
+    # backup look for a single _topic_map in the cloned directory
     if not os.path.isfile(config):
-        config = os.path.abspath(os.path.join(CLONE_DIR, "_build_cfg.yml"))
+        config = os.path.abspath(os.path.join(CLONE_DIR, "_topic_map.yml"))
 
     return config
 
-
 def parse_build_config(config):
     """
     Parses the build config and returns a tree based structure for the config.

build_for_portal.py

@@ -56,11 +56,11 @@ contain all the images and modules for the collection.
 
 == Version management
 Most of the content applies to all five OpenShift products: OKD, OpenShift
-Online, OpenShift Dedicated, Azure Red Hat OpenShift and OpenShift Container Platform. While a large
+Online, OpenShift Dedicated, ROSA and OpenShift Container Platform. While a large
 amount of content is reused for all product collections, some information
 applies to only specific collections. Content inclusion and exclusion is managed
 on the assembly level by specifying distributions in the
-`_topic_map.yml` file or by using `ifdef/endif` statements in individual
+`_topic_map.yml` files in the `_topic_maps` folder or by using `ifdef/endif` statements in individual
 files.
 
 ////
@@ -88,6 +88,7 @@ are:
 * _openshift-dedicated_
 * _openshift-aro_
 * _openshift-webscale_
+* _openshift-rosa_
 
 These attributes can be used by themselves or in conjunction to conditionalize
 text within an assembly or module.
@@ -164,12 +165,18 @@ file to determine which topic files to include. Therefore, all new assemblies th
 are created must be included in the `_topic_map.yml` file in
 order to be processed by the build system.
 
+For all supported versions, the topic map files are available in the `_topic_maps` folder. Older versions support `_topic_map.yml` file in the root folder.
+
+OpenShift Dedicated and OpenShift ROSA have their own topic maps: `_topic_map_osd.yml` and `_topic_map_rosa.yml`. Edits to these files should be coordinated with Service Delivery documentation team members as that team is primarily responsible for maintaining this content.
+
 [NOTE]
 ====
 Module files are included in the appropriate assembly files. Modules are not added directly to the `_topic_map.yml` file.
 ====
 
 === Topic map file format
+For supported branches the `_topic_map.yml` is based in the `_topic_maps` folder in the root directory and are organized (primarily) by distributions.
+
 The `_topic_map.yml` file uses the following format:
 
 ----
@@ -204,13 +211,16 @@ topic or topic group will appear in all product documentation versions.
 _openshift-origin,openshift-enterprise,openshift-online,openshift-dedicated,openshift-aro,openshift-webscale_.
 * The *all* value overrides other values, so _openshift-online,all_ is processed
 as *all*.
+* Do not use _openshift-dedicated_ or _openshift-rosa_ in the main `_topic_map.yml` file. Use the distribution specific topic map file.
 <5> Assembly name.
 <6> Assembly file under the topic group dir without `.adoc`.
 <7> This topic is actually a subtopic group. Instead of a `File` path it has a
 `Dir` path and `Topics`, just like a top-level topic group.
 <8> Assemblies belonging to a subtopic group are listed just like regular assemblies
 with a `Name` and `File`.
 
+
+
 == Next steps
 * First, you should link:tools_and_setup.adoc[install and set up the tools and software]
 on your workstation so that you can contribute.