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

linfraze · 2025-06-13T21:01:34Z

IMPORTANT: Do Not Merge - To be merged by Docs Team Only

Version(s):
1.7

Issue:
RHIDP-7202

Previews:
Configure: https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/pr-1228/techdocs/#configuring-techdocs

Generate pipeline: https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/pr-1228/techdocs/#proc-techdocs-pipeline-github-actions_assembly-techdocs-add-docs

Embed videos: https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/pr-1228/techdocs/#proc-techdocs-embed-video_assembly-techdocs-add-docs

rhdh-bot · 2025-06-13T21:04:56Z

Updated preview: https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/pr-1228/ @ 07/07/25 12:09:10

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

assemblies/assembly-configuring-techdocs.adoc

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

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

assemblies/assembly-configuring-techdocs.adoc

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

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

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

…tions and embedding videos

pabel-rh · 2025-07-09T06:34:18Z

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

+====
+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.


Suggested change

. From the {ocp-short} web console, click *Topology* > *Actions* > *Restart rollout* to restart the pod.

. To restart the pod, from the {ocp-short} web console, click *Topology > Actions > Restart rollout*.

I recommend leading with orientation and action and then explaining the why, but if you have received guidance that suggests that this format is better, then go for it. Otherwise, consider getting Ingrid's opinion on this.

Sure, Lindsey! I'll follow leading with orientation and action and the why.

pabel-rh · 2025-07-09T06:37:54Z

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

+
+.Procedure
+
+. In the section of the TechDocs file that you want to embed a video into, add the following configuration:


Suggested change

. In the section of the TechDocs file that you want to embed a video into, add the following configuration:

. In the section of the TechDocs file that you want to embed a video, add the following configuration:

I recommend leaving "into" as we embed into

pabel-rh · 2025-07-09T06:40:46Z

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

+* *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 respository.


Suggested change

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 respository.

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.

pabel-rh · 2025-07-09T06:41:41Z

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

+* 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.


Suggested change

* Minimal IAM Policies are configured for your S3 bucket, granting both Write and Read access.

* Minimal IAM policies are configured for your S3 bucket, granting both Write and Read access.

(I'm not sure if it should be lowercase or uppercase. Please ignore if this isn't applicable)

Check the UI

pabel-rh · 2025-07-09T06:41:54Z

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

+
+.Procedure
+
+. Set up the GitHub Actions workflow


Suggested change

. Set up the GitHub Actions workflow

. Set up the GitHub Actions workflow.

pabel-rh · 2025-07-09T06:49:46Z

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

+====
+
+.Verification
+. Go to your {product-very-short} instance and click *Docs* to see the TechDocs served from your Amazon S3 bucket.


Suggested change

. Go to your {product-very-short} instance and click *Docs* to see the TechDocs served from your Amazon S3 bucket.

. To see the TechDocs served from your Amazon S3 bucket, go to your {product-very-short} instance and click *Docs*.

Again, it makes sense to me to orient, state the action, and then the why, but I'm interested in hearing what Ingrid thinks about that

pabel-rh · 2025-07-09T06:50:45Z

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.


(We did have a discussion that we're not mentioned that the core plugins are "preinstalled and enabled by default".. just wanted to check if this is okay?

pabel-rh · 2025-07-09T06:51:36Z

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

+. 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, enter the following JSON content into the *Policy editor*:


Suggested change

.. On the *Create policy > Specify permissions* page, enter the following JSON content into the *Policy editor*:

.. On the *Create policy > Specify permissions* page, in the *Policy editor*, enter the following JSON content:

Be careful documenting details of a third-party UI / webpage because it could change without our knowledge at any time

pabel-rh · 2025-07-09T06:52:41Z

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

+====
+
+.Verification
+. Go to your Amazon S3 bucket to see a set of static site files in your *Objects* list.


Suggested change

. Go to your Amazon S3 bucket to see a set of static site files in your *Objects* list.

. To see a set of static site files in your *Objects* list, go to your Amazon S3 bucket.

pabel-rh · 2025-07-09T06:53:07Z

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

+====
+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:


Suggested change

. 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:

. 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:

linfraze temporarily deployed to internal June 13, 2025 21:01 — with GitHub Actions Inactive

linfraze changed the title ~~RHIDP-7202: Doc procs for generating TechDocs pipeline with GitHub Ac…~~ RHIDP-7202: Doc procs for generating TechDocs pipeline with GitHub Actions and embedding videos Jun 13, 2025

linfraze force-pushed the RHIDP-7202 branch from 3b71447 to 85ef601 Compare June 13, 2025 21:02

linfraze temporarily deployed to internal June 13, 2025 21:02 — with GitHub Actions Inactive

linfraze commented Jun 13, 2025

View reviewed changes

modules/techdocs/proc-techdocs-embed-videos.adoc Outdated Show resolved Hide resolved

linfraze force-pushed the RHIDP-7202 branch from 85ef601 to 36de625 Compare June 13, 2025 21:35

linfraze temporarily deployed to internal June 13, 2025 21:35 — with GitHub Actions Inactive

linfraze commented Jun 13, 2025

View reviewed changes

assemblies/assembly-configuring-techdocs.adoc Outdated Show resolved Hide resolved

linfraze requested a review from 04kash June 13, 2025 21:46

linfraze added do-no-merge/review-in-progress 👀 Technical review needed 🔩 Test all the procedures Peer review needed 📖 labels Jun 17, 2025

linfraze force-pushed the RHIDP-7202 branch from 36de625 to 8dcb5fb Compare June 18, 2025 18:57

linfraze temporarily deployed to internal June 18, 2025 18:57 — with GitHub Actions Inactive

linfraze commented Jun 18, 2025

View reviewed changes

modules/techdocs/proc-techdocs-embed-videos.adoc Show resolved Hide resolved

linfraze commented Jun 18, 2025

View reviewed changes

modules/techdocs/proc-techdocs-embed-videos.adoc Show resolved Hide resolved

linfraze force-pushed the RHIDP-7202 branch from 8dcb5fb to fe45e00 Compare June 18, 2025 19:07

linfraze temporarily deployed to internal June 18, 2025 19:07 — with GitHub Actions Inactive

04kash requested changes Jun 19, 2025

View reviewed changes

linfraze temporarily deployed to internal June 24, 2025 17:35 — with GitHub Actions Inactive

linfraze force-pushed the RHIDP-7202 branch from a5ef88c to c9e87bf Compare June 24, 2025 17:42

linfraze temporarily deployed to internal June 24, 2025 17:42 — with GitHub Actions Inactive

linfraze commented Jun 24, 2025

View reviewed changes

modules/techdocs/proc-techdocs-configure-amazon-s3-storage.adoc Outdated Show resolved Hide resolved

linfraze force-pushed the RHIDP-7202 branch from c9e87bf to 8415454 Compare June 24, 2025 17:49

linfraze temporarily deployed to internal June 24, 2025 17:49 — with GitHub Actions Inactive

linfraze force-pushed the RHIDP-7202 branch from 8415454 to 7a855cb Compare June 24, 2025 17:58

linfraze temporarily deployed to internal June 24, 2025 17:58 — with GitHub Actions Inactive

linfraze added 2 commits June 26, 2025 12:35

RHIDP-7202: Doc procs for generating TechDocs pipeline with GitHub Ac…

cfef236

…tions and embedding videos

RHIDP-7202: Apply SME comments

ac5bd69

linfraze force-pushed the RHIDP-7202 branch from 7a855cb to ac5bd69 Compare June 26, 2025 21:15

linfraze temporarily deployed to internal June 26, 2025 21:15 — with GitHub Actions Inactive

linfraze added Technical review done ⛅ Any procedure has been succesfully tested and removed Technical review needed 🔩 Test all the procedures labels Jun 26, 2025

Merge branch 'main' into RHIDP-7202

9d2e757

hmanwani-rh temporarily deployed to internal July 7, 2025 12:06 — with GitHub Actions Inactive

pabel-rh reviewed Jul 9, 2025

View reviewed changes

	. From the {ocp-short} web console, click Topology > Actions > Restart rollout to restart the pod.
	. To restart the pod, from the {ocp-short} web console, click Topology > Actions > Restart rollout.


		.Procedure

		. In the section of the TechDocs file that you want to embed a video into, add the following configuration:

	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 respository.
	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.

	* Minimal IAM Policies are configured for your S3 bucket, granting both Write and Read access.
	* Minimal IAM policies are configured for your S3 bucket, granting both Write and Read access.

	. Set up the GitHub Actions workflow
	. Set up the GitHub Actions workflow.

	. Go to your {product-very-short} instance and click Docs to see the TechDocs served from your Amazon S3 bucket.
	. To see the TechDocs served from your Amazon S3 bucket, go to your {product-very-short} instance and click Docs.

	.. On the Create policy > Specify permissions page, enter the following JSON content into the Policy editor:
	.. On the Create policy > Specify permissions page, in the Policy editor, enter the following JSON content:

	. Go to your Amazon S3 bucket to see a set of static site files in your Objects list.
	. To see a set of static site files in your Objects list, go to your Amazon S3 bucket.

	. 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:
	. 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:

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

Are you sure you want to change the base?

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

Uh oh!

Conversation

linfraze commented Jun 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rhdh-bot commented Jun 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

linfraze commented Jun 13, 2025 •

edited

Loading

rhdh-bot commented Jun 13, 2025 •

edited

Loading