Skip to content

Commit ac5bd69

Browse files
linfrazelinfraze
committed
RHIDP-7202: Apply SME comments
1 parent cfef236 commit ac5bd69

9 files changed

+56
-35
lines changed

‎assemblies/assembly-configuring-techdocs.adoc‎

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,9 @@ After you configure {odf-name} to store the files that TechDocs generates, you c
2222
//configuring storage
2323
include::modules/customizing-techdocs/con-techdocs-configure-storage.adoc[leveloffset=+1]
2424

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

@@ -33,14 +36,6 @@ include::modules/customizing-techdocs/proc-techdocs-configure-odf-operator.adoc[
3336

3437
include::modules/customizing-techdocs/ref-techdocs-example-config-plugin-operator.adoc[leveloffset=+4]
3538

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

42-
include::modules/customizing-techdocs/proc-techdocs-config-cicd-prep-repo.adoc[leveloffset=+2]
43-
44-
include::modules/customizing-techdocs/proc-techdocs-generate-site.adoc[leveloffset=+2]
45-
46-
include::modules/customizing-techdocs/proc-techdocs-publish-site.adoc[leveloffset=+2]

‎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/techdocs/proc-techdocs-configure-amazon-s3-storage.adoc‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010

1111
.Prerequisites
1212

13-
* You are logged in to your AWS account.
13+
* You are logged in to your AWS account as an administrator.
1414

1515
.Procedure
1616
. On the AWS console, create an AWS S3 bucket.
@@ -49,15 +49,19 @@ where
4949
_<bucket_name>_ :: Specifies the name of your Amazon S3 bucket.
5050
+
5151
.. 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.
52+
. Assign the IAM policy to a new or existing user.
5553
. Generate a new access key and a new secret access key.
5654
+
5755
[NOTE]
5856
====
5957
You can use the newly created access keys to generate a TechDocs pipeline with GitHub Actions.
6058
====
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+
====
6165

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

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

Lines changed: 7 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,11 @@
88

99
You can use `<iframe>` elements to embed videos into your TechDocs.
1010

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+
1116
.Procedure
1217

1318
. In the section of the TechDocs file that you want to embed a video into, add the following configuration:
@@ -37,7 +42,7 @@ _<frame_border>_ :: Specifies the size of the frame border in number of pixels,
3742
====
3843
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.
3944
====
40-
. In the `frame-src` and `allowedIframeHosts` fields of your `app-config.yaml` file, add any video hosts that you want to use. For example:
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:
4146
+
4247
[source,yaml,subs="+quotes,+attributes"]
4348
----
@@ -50,21 +55,11 @@ techdocs:
5055
sanitizer:
5156
allowedIframeHosts:
5257
- www.youtube.com
58+
- _<additional_video_host_url>_
5359
publisher:
5460
type: awsS3
5561
awsS3:
5662
bucketName: ${AWS_S3_BUCKET_NAME}
5763
accountId: ${AWS_ACCOUNT_ID}
5864
region: ${AWS_REGION}
5965
----
60-
+
61-
. To authenticate with AWS, add the following configuration to your `app-config.yaml` file. For example:
62-
+
63-
[source,yaml]
64-
----
65-
aws:
66-
accounts:
67-
- accountId: ${AWS_ACCOUNT_ID}
68-
accessKeyId: ${AWS_ACCESS_KEY_ID}
69-
secretAccessKey: ${AWS_SECRET_ACCESS_KEY}
70-
----

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

Lines changed: 29 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -20,35 +20,54 @@ You can implement a TechDocs pipeline using GitHub Actions to automatically gene
2020
* Your organization has documentation files stored in a remote repository.
2121
* You have an mkdocs.yaml file located in the root directory of your repository.
2222
* You have the `catalog.entity.create` and `catalog.location.create` permissions to import documentation into TechDocs from a remote repository.
23-
* You have an AWS S3 bucket created to store your TechDocs sites.
23+
* You have an AWS S3 bucket to store your TechDocs sites.
2424
* Minimal IAM Policies are configured for your S3 bucket, granting both Write and Read access.
25-
* An IAM User has been created, the necessary policy attached, and an access key generated.
25+
* An administrator has created an IAM User, attached the necessary policy, and generated an access key in the AWS console.
2626
2727
.Procedure
2828

2929
. Set up the GitHub Actions workflow
30-
.. On GitHub, create a fork of the `rhdh-techdocs-pipeline` repository.
30+
.. 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.
3131
+
3232
[NOTE]
3333
====
3434
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.
3535
====
3636
+
3737
.. Use the GitHub GUI to make sure that all of the permissions required to run the workflow are enabled.
38-
.. Add the *Repository secrets* required to connect the workflow to your AWS account.
38+
.. 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`.
3939
+
4040
[NOTE]
4141
====
4242
The default `mkdocs.yaml` file in the `rhdh-techdocs-pipeline` workflow installs the `techdocs-core` and `minify` plugins.
4343
====
4444
.. Optional: Modify the default structure of the `rhdh-techdocs-pipeline` repository or the default files within it to meet the needs of your organization.
4545
.. 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.
46-
. Update the `app-config.yaml` file to enable your Amazon S3 bucket to serve TechDocs to your {product-very-short} instance.
47-
.. In the Developer perspective of {ocp-short} console, click *ConfigMaps* and select your {product-very-short} `app-config.yaml` file.
48-
.. In the `techdocs` section of the `app-config.yaml` file, set `builder` to `external`.
49-
.. Set `publisher.type` to `awsS3`.
50-
.. 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)`.
51-
.. 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.
46+
. In the Developer perspective of {ocp-short} console, click *ConfigMaps* and select your {product-very-short} `app-config.yaml` file.
47+
. Update the `app-config.yaml` file to enable your Amazon S3 bucket to serve TechDocs to your {product-very-short} instance. For example:
48+
+
49+
[source,yaml,subs="+quotes,+attributes"]
50+
----
51+
techdocs:
52+
builder: external
53+
publisher:
54+
type: awsS3
55+
awsS3:
56+
bucketName: ${AWS_S3_BUCKET_NAME}
57+
accountId: ${AWS_ACCOUNT_ID}
58+
region: ${AWS_REGION}
59+
60+
aws:
61+
accounts:
62+
- accountId: ${AWS_ACCOUNT_ID}
63+
accessKeyId: ${AWS_ACCESS_KEY_ID}
64+
secretAccessKey: ${AWS_SECRET_ACCESS_KEY}
65+
66+
catalog:
67+
locations:
68+
- type: url
69+
target: https://github.com/_<your_org>_/rhdh-techdocs-pipeline/blob/main/catalog-info.yaml
70+
----
5271
. Click *Save*.
5372
. In the navigation menu of the {ocp-short} console, click *Topology* and restart the pod.
5473
+

0 commit comments

Comments
 (0)