Skip to content

Commit 6bc4256

Browse files
linfrazehmanwani-rhpabel-rh
authored
RHIDP-7202: Doc procs for generating TechDocs pipeline with GitHub Actions and embedding videos (#1228)
* RHIDP-7202: Doc procs for generating TechDocs pipeline with GitHub Actions and embedding videos * RHIDP-7202: Apply SME comments * Update modules/techdocs/proc-techdocs-pipeline-github-actions.adoc Co-authored-by: Priyanka Abel <[email protected]> * Update modules/techdocs/proc-techdocs-pipeline-github-actions.adoc Co-authored-by: Priyanka Abel <[email protected]> * Update modules/techdocs/proc-techdocs-pipeline-github-actions.adoc Co-authored-by: Priyanka Abel <[email protected]> * Update modules/techdocs/proc-techdocs-pipeline-github-actions.adoc Co-authored-by: Priyanka Abel <[email protected]> * Update modules/techdocs/proc-techdocs-configure-amazon-s3-storage.adoc Co-authored-by: Priyanka Abel <[email protected]> * Update modules/techdocs/proc-techdocs-embed-videos.adoc Co-authored-by: Priyanka Abel <[email protected]> --------- Co-authored-by: Heena Manwani <[email protected]> Co-authored-by: Priyanka Abel <[email protected]>
1 parent b65e98e commit 6bc4256

11 files changed

+243
-12
lines changed

‎assemblies/assembly-configuring-techdocs.adoc

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
:_mod-docs-content-type: ASSEMBLY
22
:context: configuring-techdocs
33
[id="{context}"]
4-
= TechDocs configuration
4+
= Configuring TechDocs
55

66
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.
77

@@ -19,22 +19,23 @@ After you configure {odf-name} to store the files that TechDocs generates, you c
1919

2020
* For more information, see link:{configuring-dynamic-plugins-book-url}[{configuring-dynamic-plugins-book-title}].
2121
22+
//configuring storage
2223
include::modules/customizing-techdocs/con-techdocs-configure-storage.adoc[leveloffset=+1]
2324

25+
//configuring storage - Amazon S3
26+
include::modules/techdocs/proc-techdocs-configure-amazon-s3-storage.adoc[leveloffset=+2]
27+
28+
//configuring storage - ODF
2429
include::modules/customizing-techdocs/proc-techdocs-using-odf-storage.adoc[leveloffset=+2]
2530

26-
include::modules/customizing-techdocs/proc-techdocs-configure-odf-helm.adoc[leveloffset=+2]
31+
include::modules/customizing-techdocs/proc-techdocs-configure-odf-helm.adoc[leveloffset=+3]
2732

28-
include::modules/customizing-techdocs/ref-techdocs-example-config-plugin-helm.adoc[leveloffset=+3]
33+
include::modules/customizing-techdocs/ref-techdocs-example-config-plugin-helm.adoc[leveloffset=+4]
2934

30-
include::modules/customizing-techdocs/proc-techdocs-configure-odf-operator.adoc[leveloffset=+2]
35+
include::modules/customizing-techdocs/proc-techdocs-configure-odf-operator.adoc[leveloffset=+3]
3136

32-
include::modules/customizing-techdocs/ref-techdocs-example-config-plugin-operator.adoc[leveloffset=+3]
37+
include::modules/customizing-techdocs/ref-techdocs-example-config-plugin-operator.adoc[leveloffset=+4]
3338

39+
//configuring CI/CD
3440
include::modules/customizing-techdocs/con-techdocs-config-cicd.adoc[leveloffset=+1]
3541

36-
include::modules/customizing-techdocs/proc-techdocs-config-cicd-prep-repo.adoc[leveloffset=+2]
37-
38-
include::modules/customizing-techdocs/proc-techdocs-generate-site.adoc[leveloffset=+2]
39-
40-
include::modules/customizing-techdocs/proc-techdocs-publish-site.adoc[leveloffset=+2]

‎assemblies/assembly-using-techdocs.adoc

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,9 @@ include::modules/techdocs/proc-techdocs-find-docs.adoc[leveloffset=+1]
1212
include::modules/techdocs/proc-techdocs-view-docs.adoc[leveloffset=+1]
1313

1414
include::modules/techdocs/proc-techdocs-edit-docs.adoc[leveloffset=+1]
15+
16+
//embedding videos
17+
include::modules/techdocs/proc-techdocs-embed-videos.adoc[leveloffset=+1]
18+
19+
//generating pipelines with GitHub Actions
20+
include::modules/techdocs/proc-techdocs-pipeline-github-actions.adoc[leveloffset=+1]

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
// ARCHIVED
2+
13
:_mod-docs-content-type: CONCEPT
24
[id="con-techdocs-config-cicd_{context}"]
35
= Configuring CI/CD to generate and publish TechDocs sites

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,4 @@
22
[id="con-techdocs-configure-storage_{context}"]
33
= Configuring storage for TechDocs files
44

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
// ARCHIVED
2+
13
:_mod-docs-content-type: PROCEDURE
24
[id="proc-techdocs-config-cicd-prep-repo_{context}"]
35
= Preparing your repository for CI

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
// ARCHIVED
2+
13
:_mod-docs-content-type: PROCEDURE
24
[id="proc-techdocs-generate-site_{context}"]
35
= Generating the TechDocs site

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
// ARCHIVED
2+
13
:_mod-docs-content-type: PROCEDURE
24
[id="proc-techdocs-publish-site_{context}"]
35
= Publishing the TechDocs site

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
:_mod-docs-content-type: PROCEDURE
22
[id="proc-techdocs-using-odf-storage_{context}"]
3-
= Using {odf-name} for file storage
3+
= Configuring {odf-name} for file storage
44

55
You can configure {odf-name} to store the files that TechDocs generates instead of relying on other cloud storage solutions.
66

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

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * assemblies/assembly-using-techdocs.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="proc-techdocs-configure-amazon-s3-storage_{context}"]
7+
= Configuring Amazon S3 for file storage
8+
9+
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.
10+
11+
.Prerequisites
12+
13+
* You are logged in to your AWS account as an administrator.
14+
15+
.Procedure
16+
. On the AWS console, create an AWS S3 bucket.
17+
.. On the *Create bucket* page, enter a *Bucket name* and use the default selections for all other settings.
18+
.. Create an IAM policy to give authorized users permissions to generate and publish TechDocs for your organization.
19+
.. On the *Create policy > Specify permissions* page, in the *Policy editor*, enter the following JSON content:
20+
+
21+
[source,JSON,subs="+quotes,+attributes"]
22+
----
23+
{
24+
"Version": "2012-10-17",
25+
"Statement": [
26+
{
27+
"Sid": "TechDocsList",
28+
"Effect": "Allow",
29+
"Action": "s3:ListBucket",
30+
"Resource": "arn:aws:s3:::_<bucket_name>_"
31+
},
32+
{
33+
"Sid": "TechDocsObjects",
34+
"Effect": "Allow",
35+
"Action": [
36+
"s3:GetObject",
37+
"s3:PutObject",
38+
"s3:DeleteObject",
39+
"s3:DeleteObjectVersion"
40+
],
41+
"Resource": "arn:aws:s3:::_<bucket_name>_/*"
42+
}
43+
]
44+
}
45+
----
46+
+
47+
where
48+
49+
_<bucket_name>_ :: Specifies the name of your Amazon S3 bucket.
50+
+
51+
.. On the *Create policy > Specify permissions* page, enter a *Policy name*.
52+
. Assign the IAM policy to a new or existing user.
53+
. Generate a new access key and a new secret access key.
54+
+
55+
[NOTE]
56+
====
57+
You can use the newly created access keys to generate a TechDocs pipeline with GitHub Actions.
58+
====
59+
. From the {ocp-short} web console, click *Topology* > *Actions* > *Restart rollout* to restart the pod.
60+
+
61+
[NOTE]
62+
====
63+
You must restart the pod to apply the configuration changes.
64+
====
65+
66+
.Verification
67+
. Go to your Amazon S3 bucket to see a set of static site files in your *Objects* list.
68+
////
69+
.Next steps
70+
* xref:proc-techdocs-pipeline-github-actions_{context}[Generating a TechDocs pipeline with GitHub Actions]
71+
////

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

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * assemblies/assembly-using-techdocs.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="proc-techdocs-embed-video_{context}"]
7+
= Embedding videos into TechDocs
8+
9+
You can use `<iframe>` elements to embed videos into your TechDocs.
10+
11+
.Prerequisites
12+
13+
* An administrator has configured your AWS S3 bucket to store TechDocs sites.
14+
* An administrator has configured the appropriate `techdocs.sanitizer.allowedIframeHosts` and `backend.csp` settings in your `app-config.yaml` file.
15+
16+
.Procedure
17+
18+
. In the section of the TechDocs file that you want to embed a video into, add the following configuration:
19+
+
20+
[source,yaml,subs="+quotes,+attributes"]
21+
----
22+
<iframe
23+
width="_<video_width>_"
24+
height="_<video_height>_"
25+
src="_<video_url>_"
26+
title="_<video_title>_"
27+
frameborder="_<frame_border>_"
28+
allow="picture-in-picture"
29+
allowfullscreen>
30+
</iframe>
31+
----
32+
+
33+
where
34+
35+
_<video_width>_ :: Specifies the width of the video in number of pixels, for example, `672`.
36+
_<video_height>_ :: Specifies the height of the video in number of pixels, for example, `378`.
37+
_<video_url>_ :: Specifies the url of the video, for example, `https://www.youtube.com/watch?v=LB1w8hjBt5k`.
38+
_<video_title>_ :: Specifies the title of the video, for example, `{product} Overview Video`.
39+
_<frame_border>_ :: Specifies the size of the frame border in number of pixels, for example, `0`. Use a value of `0` for no border.
40+
+
41+
[NOTE]
42+
====
43+
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.
44+
====
45+
. 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:
46+
+
47+
[source,yaml,subs="+quotes,+attributes"]
48+
----
49+
backend:
50+
csp:
51+
connect-src: ['https:']
52+
frame-src: ['https://www.youtube.com/']
53+
techdocs:
54+
builder: external
55+
sanitizer:
56+
allowedIframeHosts:
57+
- www.youtube.com
58+
- _<additional_video_host_url>_
59+
publisher:
60+
type: awsS3
61+
awsS3:
62+
bucketName: ${AWS_S3_BUCKET_NAME}
63+
accountId: ${AWS_ACCOUNT_ID}
64+
region: ${AWS_REGION}
65+
----

0 commit comments

Comments
 (0)