Skip to content

Commit 3b71447

Browse files
linfrazelinfraze
committed
RHIDP-7202: Doc procs for generating TechDocs pipeline with GitHub Actions and embedding videos
1 parent 2963f3c commit 3b71447

File tree

6 files changed

+171
-6
lines changed

6 files changed

+171
-6
lines changed

‎assemblies/assembly-configuring-techdocs.adoc‎

Lines changed: 11 additions & 5 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,18 +19,24 @@ 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 - ODF
2426
include::modules/customizing-techdocs/proc-techdocs-using-odf-storage.adoc[leveloffset=+2]
2527

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

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

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

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

36+
//configuring storage - Amazon S3
37+
include::modules/techdocs/proc-techdocs-configure-amazon-s3-storage.adoc[leveloffset=+2]
38+
39+
//configuring CI/CD
3440
include::modules/customizing-techdocs/con-techdocs-config-cicd.adoc[leveloffset=+1]
3541

3642
include::modules/customizing-techdocs/proc-techdocs-config-cicd-prep-repo.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/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: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
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.
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, enter the following JSON content into the *Policy editor*:
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+
. Create a user and assign the IAM policy.
53+
.. On the *Create user > Specify user details* page, enter a *User name*.
54+
.. On the *Create user > Set permissions* page, select *Attach policies directly* and select the permissions policy that you created.
55+
. Generate a new access key and a new secret access key.
56+
+
57+
[NOTE]
58+
====
59+
You can use the newly created access keys to generate a TechDocs pipeline with GitHub Actions.
60+
====
61+
62+
.Verification
63+
. Go to your Amazon S3 bucket to see a set of static site files in your *Objects* list.
64+
////
65+
.Next steps
66+
* xref:proc-techdocs-pipeline-github-actions_{context}[Generating a TechDocs pipeline with GitHub Actions]
67+
////

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

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
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+
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.
12+
13+
.Procedure
14+
15+
* In your `app-config.yaml` file, add the following configuration:
16+
+
17+
[source,yaml,subs="+quotes,+attributes"]
18+
----
19+
<iframe
20+
width="672"
21+
height="378"
22+
src="https://www.youtube.com/embed/LB1w8hjBt5k"
23+
title="{product} Overview"
24+
frameborder="0"
25+
allow="picture-in-picture"
26+
allowfullscreen></iframe>
27+
----

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

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
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-pipeline-github-actions_{context}"]
7+
= Generating TechDocs Pipelines with GitHub Actions
8+
9+
{product} ({product-very-short}) includes a built-in TechDocs builder that generates static HTML documentation from your codebase. Configuring the default setup of the local builder for production involves the following actions:
10+
11+
* Build the docs in CI/CD
12+
* Publish the generated site to external object storage, such as AWS S3 or Google Cloud Storage
13+
* Run TechDocs in read-only mode within your {product-very-short} instance
14+
15+
.Prerequisites
16+
17+
* The TechDocs plugin is enabled and configured on your {product-very-short} instance.
18+
* Your organization has documentation files stored in a remote repository.
19+
* You have an mkdocs.yaml file located in the root directory of your repository.
20+
* You have the `catalog.entity.create` and `catalog.location.create` permissions to import documentation into TechDocs from a remote repository.
21+
* You have an AWS S3 bucket created to store your TechDocs sites.
22+
* Minimal IAM Policies are configured for your S3 bucket, granting both Write and Read access.
23+
* An IAM User has been created, the necessary policy attached, and an access key generated.
24+
25+
.Procedure
26+
27+
. Set up the GitHub Actions workflow
28+
.. On GitHub, create a fork of the `rhdh-techdocs-pipeline` repository.
29+
+
30+
[NOTE]
31+
====
32+
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.
33+
====
34+
+
35+
.. Use the GitHub GUI to make sure that all of the permissions required to run the workflow are enabled.
36+
.. Add the *Repository secrets* required to connect the workflow to your AWS account.
37+
+
38+
[NOTE]
39+
====
40+
The default `mkdocs.yaml` file in the `rhdh-techdocs-pipeline` workflow installs the `techdocs-core` and `minify` plugins.
41+
====
42+
.. Optional: Modify the default structure of the `rhdh-techdocs-pipeline` repository or the default files within it to meet the needs of your organization.
43+
.. 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.
44+
. Update the `app-config.yaml` file to enable your Amazon S3 bucket to serve TechDocs to your {product-very-short} instance.
45+
.. In the Developer perspective of {ocp-short} console, click *ConfigMaps* and select your {product-very-short} `app-config.yaml` file.
46+
.. In the `techdocs` section of the `app-config.yaml` file, set `builder` to `external`.
47+
.. Set `publisher.type` to `awsS3`.
48+
.. In the `aws` section, set `accounts.accountId` to `$(AWS_ACCOUNT_ID)`, set `accounts.accessKeyId` to `$(AWS_ACCESS_KEY_ID)`, and set `accounts.secretAccessKey` to `$(AWS_SECRET_ACCESS_KEY)`.
49+
.. In the `catalog` section, set `locations.type` to `url` and set `locations.target` to the url to the `catalog-info.yaml` file in your `rhdh-techdocs-pipeline` repository.
50+
. Click *Save*.
51+
. In the navigation menu of the {ocp-short} console, click *Topology* and restart the pod.
52+
+
53+
[NOTE]
54+
====
55+
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.
56+
====
57+
58+
.Verification
59+
. Go to your {product-very-short} instance and click *Docs* to see the TechDocs served from your Amazon S3 bucket.

0 commit comments

Comments
 (0)