diff --git a/assemblies/assembly-configuring-techdocs.adoc b/assemblies/assembly-configuring-techdocs.adoc index 8afb63a65e..dc67415448 100644 --- a/assemblies/assembly-configuring-techdocs.adoc +++ b/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] diff --git a/assemblies/assembly-using-techdocs.adoc b/assemblies/assembly-using-techdocs.adoc index 61990c879a..1156f21eaf 100644 --- a/assemblies/assembly-using-techdocs.adoc +++ b/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] diff --git a/modules/customizing-techdocs/con-techdocs-config-cicd.adoc b/modules/customizing-techdocs/con-techdocs-config-cicd.adoc index 604542179a..d73de99d55 100644 --- a/modules/customizing-techdocs/con-techdocs-config-cicd.adoc +++ b/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 diff --git a/modules/customizing-techdocs/con-techdocs-configure-storage.adoc b/modules/customizing-techdocs/con-techdocs-configure-storage.adoc index f193aa8145..8e4cc54c3c 100644 --- a/modules/customizing-techdocs/con-techdocs-configure-storage.adoc +++ b/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}. diff --git a/modules/customizing-techdocs/proc-techdocs-config-cicd-prep-repo.adoc b/modules/customizing-techdocs/proc-techdocs-config-cicd-prep-repo.adoc index 4a4bc7a951..7bc132a3a0 100644 --- a/modules/customizing-techdocs/proc-techdocs-config-cicd-prep-repo.adoc +++ b/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 diff --git a/modules/customizing-techdocs/proc-techdocs-generate-site.adoc b/modules/customizing-techdocs/proc-techdocs-generate-site.adoc index d70d0e61c7..85d50640a7 100644 --- a/modules/customizing-techdocs/proc-techdocs-generate-site.adoc +++ b/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 diff --git a/modules/customizing-techdocs/proc-techdocs-publish-site.adoc b/modules/customizing-techdocs/proc-techdocs-publish-site.adoc index fc8e22f581..4802e911ba 100644 --- a/modules/customizing-techdocs/proc-techdocs-publish-site.adoc +++ b/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 diff --git a/modules/customizing-techdocs/proc-techdocs-using-odf-storage.adoc b/modules/customizing-techdocs/proc-techdocs-using-odf-storage.adoc index d6a76639b7..34a3f7234d 100644 --- a/modules/customizing-techdocs/proc-techdocs-using-odf-storage.adoc +++ b/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. diff --git a/modules/techdocs/proc-techdocs-configure-amazon-s3-storage.adoc b/modules/techdocs/proc-techdocs-configure-amazon-s3-storage.adoc new file mode 100644 index 0000000000..9e6dd2b875 --- /dev/null +++ b/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:::__" + }, + { + "Sid": "TechDocsObjects", + "Effect": "Allow", + "Action": [ + "s3:GetObject", + "s3:PutObject", + "s3:DeleteObject", + "s3:DeleteObjectVersion" + ], + "Resource": "arn:aws:s3:::__/*" + } + ] +} +---- ++ +where + +__ :: 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] +//// diff --git a/modules/techdocs/proc-techdocs-embed-videos.adoc b/modules/techdocs/proc-techdocs-embed-videos.adoc new file mode 100644 index 0000000000..d90317c7d3 --- /dev/null +++ b/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 ` +---- ++ +where + +__ :: Specifies the width of the video in number of pixels, for example, `672`. +__ :: Specifies the height of the video in number of pixels, for example, `378`. +__ :: Specifies the url of the video, for example, `https://www.youtube.com/watch?v=LB1w8hjBt5k`. +__ :: Specifies the title of the video, for example, `{product} Overview Video`. +__ :: 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 `