Red Hat Developer Hub 1.9

Manage and consume technical documentation within Red Hat Developer Hub

Managing the documentation lifecycle - add, search, view, and edit content - using the TechDocs plugin in Red Hat Developer Hub (RHDH)

Red Hat Customer Content Services

Abstract

The TechDocs plugin empowers developers by providing a complete documentation lifecycle management tool. Authorized administrators set up the service, allowing developers to manage documentation directly in Red Hat Developer Hub (RHDH), including adding new content, searching, viewing, and making edits.

1. Adding documentation to TechDocs for your project
- 1.1. Importing documentation into TechDocs from a remote repository
2. Search for relevant content
3. Access and navigate documentation
4. Making changes to project documentation in TechDocs
5. Adding video content to enhance TechDocs
6. Streamlining documentation builds using GitHub Actions

1. Adding documentation to TechDocs for your project

After an administrator configures the TechDocs plugin, a developer can add documentation to TechDocs by importing it from a remote repository. Any authorized user or group can access the documentation that is imported into the TechDocs plugin.

1.1. Importing documentation into TechDocs from a remote repository

Teams can store their documentation files in the same remote repository where they store their code files. You can import documentation into your TechDocs plugin from a remote repository that contains the documentation files that your team uses.

Prerequisites

Your organization has documentation files stored in a remote repository.
You have a mkdocs.yaml file 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.

Procedure

In your Red Hat Developer Hub instance, click Catalog > Self-service > Register Existing Component.
In the Select URL box, enter the URL to the catalog-info.yaml file that you want to import from your repository using the following format:
https://github.com/<project_name>/<repo_name>/blob/<branch_name>/<file_directory>/catalog-info.yaml
Click Analyze
Click Finish

Verification

In the Red Hat Developer Hub navigation menu, click Docs.
Verify that the documentation that you imported is listed in the table on the Documentation page.

2. Search for relevant content

To quickly find the information required for your services, search or filter the TechDocs catalog. Narrowing your search makes sure you find relevant resources without browsing multiple repositories.

Procedure

In the Red Hat Developer Hub navigation menu, click Docs.
On the Documentation page, use the Search bar or filters to locate your document:
- Search: Enter keywords to find specific terms within documents.
- Filter by Owner: View documents owned by specific users or groups.
- Filter by Tags: Narrow results by specific labels or categories.
- Filter by Owned: View documents belonging to you or your group.
- Filter by Starred: View your bookmarked favorites.

The results update automatically to show the number of documents that meet your criteria.

3. Access and navigate documentation

Use the built-in navigation tools to move between related documents within a book. This ensures you can easily reference implementation details and requirements in a logical sequence.

Procedure

In the Red Hat Developer Hub navigation menu, click Docs.
In the Documentation table, click the name of the document you want to view.
Navigate the content using the following on-screen tools:
- Search bar: Find keywords within the current document.
- Table of contents: Jump to specific sections.
- Navigation menu: Switch between different documents in the same book.
- Next: Proceed to the next sequential document.
- Add-ons: Perform additional actions if plugins are configured, such as setting the text size.

4. Making changes to project documentation in TechDocs

You can edit a document in your TechDocs plugin directly from the document book page. Any authorized user in your organization can edit a document regardless of whether or not they are the owner of the document.

Procedure

In the Red Hat Developer Hub navigation menu, click Docs.
In the Documentation table, click the name of the document that you want to edit.
In the document, click the Edit this page icon to open the document in your remote repository.
In your remote repository, edit the document as needed.
Use the repository provider UI and your usual team processes to commit and merge your changes.

5. Adding video content to enhance TechDocs

You can use <iframe> elements to add video content to enhance your experience with TechDocs.

Prerequisites

An administrator has configured your AWS S3 bucket to store TechDocs sites.
An administrator has configured the appropriate techdocs.sanitizer.allowedIframeHosts and backend.csp settings in your app-config.yaml file.

Procedure

In the section of the TechDocs file that you want to embed a video into, add the following configuration:
```
<iframe
  width="<video_width>"
  height="<video_height>"
  src="<video_url>"
  title="<video_title>"
  frameborder="<frame_border>"
  allow="picture-in-picture"
  allowfullscreen>
</iframe>
```
where
<video_width>
Specifies the width of the video in number of pixels, for example, 672.
<video_height>
Specifies the height of the video in number of pixels, for example, 378.
<video_url>
Specifies the url of the video, for example, https://www.youtube.com/watch?v=LB1w8hjBt5k.
<video_title>
Specifies the title of the video, for example, Red Hat Developer Hub Overview Video.
<frame_border>
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 <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:

backend:
        csp:
connect-src: ['https:']
frame-src: ['https://www.youtube.com/']
techdocs:
  builder: external
  sanitizer:
    allowedIframeHosts:
      - www.youtube.com
      - <additional_video_host_url>
  publisher:
    type: awsS3
    awsS3:
      bucketName: ${AWS_S3_BUCKET_NAME}
      accountId: ${AWS_ACCOUNT_ID}
      region: ${AWS_REGION}

6. Streamlining documentation builds using GitHub Actions

Red Hat Developer Hub (RHDH) includes a built-in TechDocs builder, however, the default setup is not intended for production use. Deploying TechDocs documentation in a production environment involves the following actions:

Building the documentation in a CI/CD system
Publishing the generated documentation site to external object storage, such as AWS S3, to ensure that the generated documentation persists between restarts of RHDH and can handle larger documentation workloads.
Configuring TechDocs in your RHDH 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 repository.

Prerequisites

The TechDocs plugin is enabled and configured on your RHDH instance.
Your organization has documentation files stored in a remote repository.
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.
An administrator has created an IAM User, attached the necessary policy, and generated an access key in the AWS console.

Procedure

Set up the GitHub Actions workflow.
1. On GitHub, create a fork of the RHDH TechDocs Pipeline repository.
  Note
  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.
2. Use the GitHub GUI to make sure that all of the permissions required to run the workflow are enabled.
3. 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.
  Note
  The default mkdocs.yaml file in the rhdh-techdocs-pipeline workflow installs the techdocs-core and minify plugins.
4. Optional: Customize the default structure or files of the rhdh-techdocs-pipeline repository to meet the needs of your organization.
5. 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.
. In the navigation menu of the OpenShift Container Platform console, click ConfigMaps and select your RHDH app-config.yaml file.

Update the app-config.yaml file to enable your Amazon S3 bucket to serve TechDocs to your RHDH instance. For example:

techdocs:
  builder: external
  publisher:
    type: awsS3
    awsS3:
      bucketName: ${AWS_S3_BUCKET_NAME}
      accountId: ${AWS_ACCOUNT_ID}
      region: ${AWS_REGION}

aws:
  accounts:
    - accountId: ${AWS_ACCOUNT_ID}
      accessKeyId: ${AWS_ACCESS_KEY_ID}
      secretAccessKey: ${AWS_SECRET_ACCESS_KEY}

catalog:
     locations:
        - type: url
          target: https://github.com/<your_org>/rhdh-techdocs-pipeline/blob/main/catalog-info.yaml

Click Save.
In the navigation menu of the OpenShift Container Platform console, click Topology and restart the pod.
Note
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.

Verification

Go to your RHDH instance and click Docs to see the TechDocs served from your Amazon S3 bucket.

Legal Notice

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.