RHIDP-7202: Doc procs for generating TechDocs pipeline with GitHub Actions and embedding videos

assemblies/assembly-configuring-techdocs.adoc

@@ -1,7 +1,7 @@
 :_mod-docs-content-type: ASSEMBLY
 :context: configuring-techdocs
 [id="{context}"]
-= TechDocs configuration
+= Configuring TechDocs
 
 The TechDocs plugin is preinstalled and enabled on a {product-short} instance by default. You can disable or enable the TechDocs plugin, and change other parameters, by configuring the {product} Helm chart or the {product} Operator ConfigMap.
 
@@ -19,22 +19,23 @@ After you configure {odf-name} to store the files that TechDocs generates, you c
 
 * For more information, see link:{configuring-dynamic-plugins-book-url}[{configuring-dynamic-plugins-book-title}].
 
+//configuring storage
 include::modules/customizing-techdocs/con-techdocs-configure-storage.adoc[leveloffset=+1]
 
+//configuring storage - Amazon S3
+include::modules/techdocs/proc-techdocs-configure-amazon-s3-storage.adoc[leveloffset=+2]
+
+//configuring storage - ODF
 include::modules/customizing-techdocs/proc-techdocs-using-odf-storage.adoc[leveloffset=+2]
 
-include::modules/customizing-techdocs/proc-techdocs-configure-odf-helm.adoc[leveloffset=+2]
+include::modules/customizing-techdocs/proc-techdocs-configure-odf-helm.adoc[leveloffset=+3]
 
-include::modules/customizing-techdocs/ref-techdocs-example-config-plugin-helm.adoc[leveloffset=+3]
+include::modules/customizing-techdocs/ref-techdocs-example-config-plugin-helm.adoc[leveloffset=+4]
 
-include::modules/customizing-techdocs/proc-techdocs-configure-odf-operator.adoc[leveloffset=+2]
+include::modules/customizing-techdocs/proc-techdocs-configure-odf-operator.adoc[leveloffset=+3]
 
-include::modules/customizing-techdocs/ref-techdocs-example-config-plugin-operator.adoc[leveloffset=+3]
+include::modules/customizing-techdocs/ref-techdocs-example-config-plugin-operator.adoc[leveloffset=+4]
 
+//configuring CI/CD
 include::modules/customizing-techdocs/con-techdocs-config-cicd.adoc[leveloffset=+1]
 
-include::modules/customizing-techdocs/proc-techdocs-config-cicd-prep-repo.adoc[leveloffset=+2]
-
-include::modules/customizing-techdocs/proc-techdocs-generate-site.adoc[leveloffset=+2]
-
-include::modules/customizing-techdocs/proc-techdocs-publish-site.adoc[leveloffset=+2]

assemblies/assembly-using-techdocs.adoc

@@ -12,3 +12,9 @@ include::modules/techdocs/proc-techdocs-find-docs.adoc[leveloffset=+1]
 include::modules/techdocs/proc-techdocs-view-docs.adoc[leveloffset=+1]
 
 include::modules/techdocs/proc-techdocs-edit-docs.adoc[leveloffset=+1]
+
+//embedding videos
+include::modules/techdocs/proc-techdocs-embed-videos.adoc[leveloffset=+1]
+
+//generating pipelines with GitHub Actions
+include::modules/techdocs/proc-techdocs-pipeline-github-actions.adoc[leveloffset=+1]

modules/customizing-techdocs/con-techdocs-config-cicd.adoc

@@ -1,3 +1,5 @@
+// ARCHIVED
+
 :_mod-docs-content-type: CONCEPT
 [id="con-techdocs-config-cicd_{context}"]
 = Configuring CI/CD to generate and publish TechDocs sites

modules/customizing-techdocs/con-techdocs-configure-storage.adoc

@@ -2,4 +2,4 @@
 [id="con-techdocs-configure-storage_{context}"]
 = Configuring storage for TechDocs files
 
-The TechDocs publisher stores generated files in local storage or in cloud storage, such as {odf-name}, Google GCS, AWS S3, or Azure Blob Storage.
+The TechDocs publisher stores generated files in local storage or in cloud storage, such as AWS S3 or {odf-name}.

modules/customizing-techdocs/proc-techdocs-config-cicd-prep-repo.adoc

@@ -1,3 +1,5 @@
+// ARCHIVED
+
 :_mod-docs-content-type: PROCEDURE
 [id="proc-techdocs-config-cicd-prep-repo_{context}"]
 = Preparing your repository for CI

modules/customizing-techdocs/proc-techdocs-generate-site.adoc

@@ -1,3 +1,5 @@
+// ARCHIVED
+
 :_mod-docs-content-type: PROCEDURE
 [id="proc-techdocs-generate-site_{context}"]
 = Generating the TechDocs site

modules/customizing-techdocs/proc-techdocs-publish-site.adoc

@@ -1,3 +1,5 @@
+// ARCHIVED
+
 :_mod-docs-content-type: PROCEDURE
 [id="proc-techdocs-publish-site_{context}"]
 = Publishing the TechDocs site

modules/customizing-techdocs/proc-techdocs-using-odf-storage.adoc

@@ -1,6 +1,6 @@
 :_mod-docs-content-type: PROCEDURE
 [id="proc-techdocs-using-odf-storage_{context}"]
-= Using {odf-name} for file storage
+= Configuring {odf-name} for file storage
 
 You can configure {odf-name} to store the files that TechDocs generates instead of relying on other cloud storage solutions.
 

modules/techdocs/proc-techdocs-configure-amazon-s3-storage.adoc

@@ -0,0 +1,71 @@
+// Module included in the following assemblies:
+//
+// * assemblies/assembly-using-techdocs.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="proc-techdocs-configure-amazon-s3-storage_{context}"]
+= Configuring Amazon S3 for file storage
+
+ You can create a dedicated Amazon S3 bucket to store TechDocs sites. {product} uploads TechDocs to this bucket and serves them from the same location.
+
+.Prerequisites
+
+* You are logged in to your AWS account as an administrator.
+
+.Procedure
+. On the AWS console, create an AWS S3 bucket.
+.. On the *Create bucket* page, enter a *Bucket name* and use the default selections for all other settings.
+.. Create an IAM policy to give authorized users permissions to generate and publish TechDocs for your organization.
+.. On the *Create policy > Specify permissions* page, in the *Policy editor*, enter the following JSON content:
++
+[source,JSON,subs="+quotes,+attributes"]
+----
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Sid": "TechDocsList",
+            "Effect": "Allow",
+            "Action": "s3:ListBucket",
+            "Resource": "arn:aws:s3:::_<bucket_name>_"
+        },
+        {
+            "Sid": "TechDocsObjects",
+            "Effect": "Allow",
+            "Action": [
+                "s3:GetObject",
+                "s3:PutObject",
+                "s3:DeleteObject",
+                "s3:DeleteObjectVersion"
+            ],
+            "Resource": "arn:aws:s3:::_<bucket_name>_/*"
+        }
+    ]
+}
+----
++
+where
+
+_<bucket_name>_ :: Specifies the name of your Amazon S3 bucket.
++
+.. On the *Create policy > Specify permissions* page, enter a *Policy name*.
+. Assign the IAM policy to a new or existing user.
+. Generate a new access key and a new secret access key.
++
+[NOTE]
+====
+You can use the newly created access keys to generate a TechDocs pipeline with GitHub Actions.
+====
+. From the {ocp-short} web console, click *Topology* > *Actions* > *Restart rollout* to restart the pod.
++
+[NOTE]
+====
+You must restart the pod to apply the configuration changes.
+====
+
+.Verification
+. Go to your Amazon S3 bucket to see a set of static site files in your *Objects* list.
+////
+.Next steps
+* xref:proc-techdocs-pipeline-github-actions_{context}[Generating a TechDocs pipeline with GitHub Actions]
+////

modules/techdocs/proc-techdocs-embed-videos.adoc

@@ -0,0 +1,65 @@
+// Module included in the following assemblies:
+//
+// * assemblies/assembly-using-techdocs.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="proc-techdocs-embed-video_{context}"]
+= Embedding videos into TechDocs
+
+You can use `<iframe>` elements to embed videos into your TechDocs.
+
+.Prerequisites
+
+* An administrator has configured your AWS S3 bucket to store TechDocs sites.
+* An administrator has configured the appropriate `techdocs.sanitizer.allowedIframeHosts` and `backend.csp` settings in your `app-config.yaml` file.
+
+.Procedure
+
+. In the section of the TechDocs file that you want to embed a video into, add the following configuration:
++
+[source,yaml,subs="+quotes,+attributes"]
+----
+<iframe
+  width="_<video_width>_"
+  height="_<video_height>_"
+  src="_<video_url>_"
+  title="_<video_title>_"
+  frameborder="_<frame_border>_"
+  allow="picture-in-picture"
+  allowfullscreen>
+</iframe>
+----
++
+where
+
+_<video_width>_ :: Specifies the width of the video in number of pixels, for example, `672`.
+_<video_height>_ :: Specifies the height of the video in number of pixels, for example, `378`.
+_<video_url>_ :: Specifies the url of the video, for example, `https://www.youtube.com/watch?v=LB1w8hjBt5k`.
+_<video_title>_ :: Specifies the title of the video, for example, `{product} Overview Video`.
+_<frame_border>_ :: Specifies the size of the frame border in number of pixels, for example, `0`. Use a value of `0` for no border.
++
+[NOTE]
+====
+TechDocs uses DOMPurify to sanitize HTML. To prevent DOMPurify from removing the `<iframe>` elements, you must list every permitted video host, such as www.youtube.com, under the `techdocs.sanitizer.allowedIframeHosts` section of your `app-config.yaml` file. You must also add the video host to the `backend.csp` section of your `app-config.yaml` file.
+====
+. In the `frame-src` and `allowedIframeHosts` fields of your `app-config.yaml` file, add any video hosts that you want to use. You can add multiple hosts. For example:
++
+[source,yaml,subs="+quotes,+attributes"]
+----
+backend:
+        csp:
+connect-src: ['https:']
+frame-src: ['https://www.youtube.com/']
+techdocs:
+  builder: external
+  sanitizer:
+    allowedIframeHosts:
+      - www.youtube.com
+      - _<additional_video_host_url>_
+  publisher:
+    type: awsS3
+    awsS3:
+      bucketName: ${AWS_S3_BUCKET_NAME}
+      accountId: ${AWS_ACCOUNT_ID}
+      region: ${AWS_REGION}
+----

modules/techdocs/proc-techdocs-pipeline-github-actions.adoc

@@ -0,0 +1,80 @@
+// Module included in the following assemblies:
+//
+// * assemblies/assembly-using-techdocs.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="proc-techdocs-pipeline-github-actions_{context}"]
+= Generating TechDocs Pipelines with GitHub Actions
+
+{product} ({product-very-short}) includes a built-in TechDocs builder, however, the default setup is not intended for production use. Deploying TechDocs documentation in a production environment involves the following actions:
+
+* *Building the documentation in a CI/CD system*
+* *Publishing the generated documentation site to external object storage*, such as AWS S3, to ensure that the generated documentation persists between restarts of {product-very-short} and can handle larger documentation workloads.
+* *Configuring TechDocs in your {product-very-short} deployment to run in read-only mode* so that TechDocs reads the static generated documentation files from the cloud storage bucket without attempting to generate them at runtime.
+
+You can implement a TechDocs pipeline using GitHub Actions to automatically generate and publish your TechDocs whenever a user in your organization makes a change to a documentation file stored in your GitHub repository.
+
+.Prerequisites
+
+* The TechDocs plugin is enabled and configured on your {product-very-short} instance.
+* Your organization has documentation files stored in a remote repository.
+* You have an mkdocs.yaml file located in the root directory of your repository.
+* You have the `catalog.entity.create` and `catalog.location.create` permissions to import documentation into TechDocs from a remote repository.
+* You have an AWS S3 bucket to store your TechDocs sites.
+* Minimal IAM Policies are configured for your S3 bucket, granting both Write and Read access.
+* An administrator has created an IAM User, attached the necessary policy, and generated an access key in the AWS console.
+
+.Procedure
+
+. Set up the GitHub Actions workflow.
+.. On GitHub, create a fork of the link:https://github.com/redhat-developer/red-hat-developer-hub-customization-provider[`red-hat-developer-hub-customization-provider`] repository.
++
+[NOTE]
+====
+The `rhdh-techdocs-pipeline` repository contains a `generate-and-publish-techdocs.yaml` workflow that automatically generates TechDocs from the docs folder and publishes them to an Amazon S3 bucket.
+====
++
+.. Use the GitHub GUI to make sure that all of the permissions required to run the workflow are enabled.
+.. Add the *Repository secrets* required to connect the workflow to your AWS account, for example, `TECHDOCS_S3_BUCKET_NAME`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`.
++
+[NOTE]
+====
+The default `mkdocs.yaml` file in the `rhdh-techdocs-pipeline` workflow installs the `techdocs-core` and `minify` plugins.
+====
+.. Optional: Customize the default structure or files of the `rhdh-techdocs-pipeline` repository to meet the needs of your organization.
+.. Optional: Add other `mkdocs` plugins that you want to use by adding the name of the plugins to the `plugins` section of the `mkdocs.yaml` file and to the `steps.name: install mkdocs and mkdocs plugins` section of the `generate-and-publish-techdocs.yaml` file.
+. . In the navigation menu of the {ocp-short} console, click *ConfigMaps* and select your {product-very-short} `app-config.yaml` file.
+. Update the `app-config.yaml` file to enable your Amazon S3 bucket to serve TechDocs to your {product-very-short} instance. For example:
++
+[source,yaml,subs="+quotes,+attributes"]
+----
+techdocs:
+  builder: external
+  publisher:
+    type: awsS3
+    awsS3:
+      bucketName: ${AWS_S3_BUCKET_NAME}
+      accountId: ${AWS_ACCOUNT_ID}
+      region: ${AWS_REGION}
+
+aws:
+  accounts:
+    - accountId: ${AWS_ACCOUNT_ID}
+      accessKeyId: ${AWS_ACCESS_KEY_ID}
+      secretAccessKey: ${AWS_SECRET_ACCESS_KEY}
+
+catalog:
+     locations:
+        - type: url
+          target: https://github.com/_<your_org>_/rhdh-techdocs-pipeline/blob/main/catalog-info.yaml
+----
+. Click *Save*.
+. In the navigation menu of the {ocp-short} console, click *Topology* and restart the pod.
++
+[NOTE]
+====
+Changes to the `docs` folder or the `mkdocs.yaml` file trigger the `rhdh-techdocs-pipeline` workflow to run. After the `rhdh-techdocs-pipeline` workflow runs successfully, the generated TechDocs are uploaded to your Amazon S3 bucket.
+====
+
+.Verification
+. Go to your {product-very-short} instance and click *Docs* to see the TechDocs served from your Amazon S3 bucket.