SupportConsoleDevelopersStart a trialContact

Chapter 6. Configuring TechDocs

Configure the Red Hat Developer Hub TechDocs plugin to create, find, and use documentation in a central location and in a standardized way. For example:

Docs-like-code approach
Write your technical documentation in Markdown files that are stored inside your project repository along with your code.
Documentation site generation
Use MkDocs to create a full-featured, Markdown-based, static HTML site for your documentation that is rendered centrally in Developer Hub.
Documentation site metadata and integrations
See additional metadata about the documentation site alongside the static documentation, such as the date of the last update, the site owner, top contributors, open GitHub issues, Slack support channels, and Stack Overflow Enterprise tags.
Built-in navigation and search
Find the information that you want from a document more quickly and easily.
Add-ons
Customize your TechDocs experience with Add-ons to address higher-order documentation needs.

The TechDocs plugin is preinstalled and enabled on a Developer Hub instance by default. You can disable or enable the TechDocs plugin, and change other parameters, by configuring the Red Hat Developer Hub Helm chart or the Red Hat Developer Hub Operator config map.

Important

Red Hat Developer Hub includes a built-in TechDocs builder that generates static HTML documentation from your codebase. However, the default basic setup of the local builder is not intended for production.

You can use a CI/CD pipeline with the repository that has a dedicated job to generate docs for TechDocs. The generated static files are stored in OpenShift Data Foundation or in a cloud storage solution of your choice and published to a static HTML documentation site.

After you configure OpenShift Data Foundation to store the files that TechDocs generates, you can configure the TechDocs plugin to use the OpenShift Data Foundation for cloud storage.

Additional resources

6.1. Configuring storage for TechDocs files

The TechDocs publisher stores generated files in local storage or in cloud storage, such as OpenShift Data Foundation, Google GCS, AWS S3, or Azure Blob Storage.

6.1.1. Using OpenShift Data Foundation for file storage

You can configure OpenShift Data Foundation to store the files that TechDocs generates instead of relying on other cloud storage solutions.

OpenShift Data Foundation provides an ObjectBucketClaim custom resource (CR) that you can use to request an S3 compatible bucket backend. You must install the OpenShift Data Foundation Operator to use this feature.

Prerequisites

Procedure

  • Create an ObjectBucketClaim CR where the generated TechDocs files are stored. For example: 

    apiVersion: objectbucket.io/v1alpha1
kind: ObjectBucketClaim
metadata:
  name: <rhdh_bucket_claim_name>
spec:
  generateBucketName: <rhdh_bucket_claim_name>
  storageClassName: openshift-storage.noobaa.io
    Note

    Creating the Developer Hub ObjectBucketClaim CR automatically creates both the Developer Hub ObjectBucketClaim config map and secret. The config map and secret have the same name as the ObjetBucketClaim CR.

After you create the ObjectBucketClaim CR, you can use the information stored in the config map and secret to make the information accessible to the Developer Hub container as environment variables. Depending on the method that you used to install Developer Hub, you add the access information to either the Red Hat Developer Hub Helm chart or Operator configuration.

Additional resources

6.1.2. Making object storage accessible to containers by using the Helm chart

Creating a ObjectBucketClaim custom resource (CR) automatically generates both the Developer Hub ObjectBucketClaim config map and secret. The config map and secret contain ObjectBucket access information. Adding the access information to the Helm chart configuration makes it accessible to the Developer Hub container by adding the following environment variables to the container:

  • BUCKET_NAME
  • BUCKET_HOST
  • BUCKET_PORT
  • BUCKET_REGION
  • BUCKET_SUBREGION
  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY

These variables are then used in the TechDocs plugin configuration.

Prerequisites

  • You have installed Red Hat Developer Hub on OpenShift Container Platform using the Helm chart.
  • You have created an ObjectBucketClaim CR for storing files generated by TechDocs. For more information see Using OpenShift Data Foundation for file storage

Procedure

  • In the upstream.backstage key in the Helm chart values, enter the name of the Developer Hub ObjectBucketClaim secret as the value for the extraEnvVarsSecrets field and the extraEnvVarsCM field. For example: 

    upstream:
  backstage:
    extraEnvVarsSecrets:
      - <rhdh_bucket_claim_name>
    extraEnvVarsCM:
      - <rhdh_bucket_claim_name>

6.1.2.1. Example TechDocs Plugin configuration for the Helm chart

The following example shows a Developer Hub Helm chart configuration for the TechDocs plugin: 

global:
  dynamic:
    includes:
      - 'dynamic-plugins.default.yaml'
  plugins:
    - disabled: false
      package: ./dynamic-plugins/dist/backstage-plugin-techdocs-backend-dynamic
      pluginConfig:
        techdocs:
          builder: external
          generator:
            runIn: local
          publisher:
            awsS3:
              bucketName: '${BUCKET_NAME}'
              credentials:
                accessKeyId: '${AWS_ACCESS_KEY_ID}'
                secretAccessKey: '${AWS_SECRET_ACCESS_KEY}'
              endpoint: 'https://${BUCKET_HOST}'
              region: '${BUCKET_REGION}'
              s3ForcePathStyle: true
            type: awsS3

6.1.3. Making object storage accessible to containers by using the Operator

Creating a ObjectBucketClaim Custom Resource (CR) automatically generates both the Developer Hub ObjectBucketClaim config map and secret. The config map and secret contain ObjectBucket access information. Adding the access information to the Operator configuration makes it accessible to the Developer Hub container by adding the following environment variables to the container:

  • BUCKET_NAME
  • BUCKET_HOST
  • BUCKET_PORT
  • BUCKET_REGION
  • BUCKET_SUBREGION
  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY

These variables are then used in the TechDocs plugin configuration.

Prerequisites

  • You have installed Red Hat Developer Hub on OpenShift Container Platform using the Operator.
  • You have created an ObjectBucketClaim CR for storing files generated by TechDocs.

Procedure

  • In the Developer Hub Backstage CR, enter the name of the Developer Hub ObjectBucketClaim config map as the value for the spec.application.extraEnvs.configMaps field and enter the Developer Hub ObjectBucketClaim secret name as the value for the spec.application.extraEnvs.secrets field. For example: 

    apiVersion: objectbucket.io/v1alpha1
kind: Backstage
metadata:
 name: <name>
spec:
  application:
    extraEnvs:
      configMaps:
        - name: <rhdh_bucket_claim_name>
      secrets:
        - name: <rhdh_bucket_claim_name>

6.1.3.1. Example TechDocs Plugin configuration for the Operator

The following example shows a Red Hat Developer Hub Operator config map configuration for the TechDocs plugin: 

kind: ConfigMap
apiVersion: v1
metadata:
  name: dynamic-plugins-rhdh
data:
  dynamic-plugins.yaml: |
    includes:
      - dynamic-plugins.default.yaml
    plugins:
      - disabled: false
        package: ./dynamic-plugins/dist/backstage-plugin-techdocs-backend-dynamic
        pluginConfig:
          techdocs:
            builder: external
            generator:
              runIn: local
            publisher:
              awsS3:
                bucketName: '${BUCKET_NAME}'
                credentials:
                  accessKeyId: '${AWS_ACCESS_KEY_ID}'
                  secretAccessKey: '${AWS_SECRET_ACCESS_KEY}'
                endpoint: 'https://${BUCKET_HOST}'
                region: '${BUCKET_REGION}'
                s3ForcePathStyle: true
              type: awsS3

6.2. Configuring CI/CD to generate and publish TechDocs sites

TechDocs reads the static generated documentation files from a cloud storage bucket, such as OpenShift Data Foundation. The documentation site is generated on the CI/CD workflow associated with the repository containing the documentation files. You can generate docs on CI and publish to a cloud storage using the techdocs-cli CLI tool.

You can use the following example to create a script for TechDocs publication: 

# Prepare
REPOSITORY_URL='https://github.com/org/repo'
git clone $REPOSITORY_URL
cd repo

# Install @techdocs/cli, mkdocs and mkdocs plugins
npm install -g @techdocs/cli
pip install "mkdocs-techdocs-core==1.*"

# Generate
techdocs-cli generate --no-docker

# Publish
techdocs-cli publish --publisher-type awsS3 --storage-name <bucket/container> --entity <Namespace/Kind/Name>

The TechDocs workflow starts the CI when a user makes changes in the repository containing the documentation files. You can configure the workflow to start only when files inside the docs/ directory or mkdocs.yml are changed.

6.2.1. Preparing your repository for CI

The first step on the CI is to clone your documentation source repository in a working directory.

Procedure

  • To clone your documentation source repository in a working directory, enter the following command: 

    git clone <https://path/to/docs-repository/>

6.2.2. Generating the TechDocs site

Procedure

To configure CI/CD to generate your techdocs, complete the following steps:

  1. Install the npx package to run techdocs-cli using the following command: 

    npm install -g npx

  2. Install the techdocs-cli tool using the following command: 

    npm install -g @techdocs/cli

  3. Install the mkdocs plugins using the following command: 

    pip install "mkdocs-techdocs-core==1.*"

  4. Generate your techdocs site using the following command: 

    npx @techdocs/cli generate --no-docker --source-dir <path_to_repo> --output-dir ./site

    Where <path_to_repo> is the location in the file path that you used to clone your repository.

6.2.3. Publishing the TechDocs site

Procedure

To publish your techdocs site, complete the following steps:

  1. Set the necessary authentication environment variables for your cloud storage provider.

  2. Publish your techdocs using the following command: 

    npx @techdocs/cli publish --publisher-type <awsS3|googleGcs> --storage-name <bucket/container> --entity <namespace/kind/name> --directory ./site

  3. Add a .github/workflows/techdocs.yml file in your Software Template(s). For example: 

    name: Publish TechDocs Site

on:
 push:
   branches: [main]
   # You can even set it to run only when TechDocs related files are updated.
   # paths:
   #   - "docs/**"
   #   - "mkdocs.yml"

jobs:
 publish-techdocs-site:
   runs-on: ubuntu-latest

   # The following secrets are required in your CI environment for publishing files to AWS S3.
   # e.g. You can use GitHub Organization secrets to set them for all existing and new repositories.
   env:
     TECHDOCS_S3_BUCKET_NAME: ${{ secrets.TECHDOCS_S3_BUCKET_NAME }}
     AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
     AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
     AWS_REGION: ${{ secrets.AWS_REGION }}
     ENTITY_NAMESPACE: 'default'
     ENTITY_KIND: 'Component'
     ENTITY_NAME: 'my-doc-entity'
     # In a Software template, Scaffolder will replace {{cookiecutter.component_id | jsonify}}
     # with the correct entity name. This is same as metadata.name in the entity's catalog-info.yaml
     # ENTITY_NAME: '{{ cookiecutter.component_id | jsonify }}'

   steps:
     - name: Checkout code
       uses: actions/checkout@v3

     - uses: actions/setup-node@v3
     - uses: actions/setup-python@v4
       with:
         python-version: '3.9'

     - name: Install techdocs-cli
       run: sudo npm install -g @techdocs/cli

     - name: Install mkdocs and mkdocs plugins
       run: python -m pip install mkdocs-techdocs-core==1.*

     - name: Generate docs site
       run: techdocs-cli generate --no-docker --verbose

     - name: Publish docs site
       run: techdocs-cli publish --publisher-type awsS3 --storage-name $TECHDOCS_S3_BUCKET_NAME --entity $ENTITY_NAMESPACE/$ENTITY_KIND/$ENTITY_NAME
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.