Chapter 6. Configuring TechDocs
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 For more information, see Configuring plugins in Red Hat Developer Hub . 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 An OpenShift Container Platform administrator has installed the OpenShift Data Foundation Operator in Red Hat OpenShift Container Platform. For more information, see OpenShift Container Platform - Installing Red Hat OpenShift Data Foundation Operator . An OpenShift Container Platform administrator has created an OpenShift Data Foundation cluster and configured the StorageSystem schema. For more information, see OpenShift Container Platform - Creating an OpenShift Data Foundation cluster . 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 ObjectBucketClaim 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 For more information about the Object Bucket Claim, see OpenShift Container Platform - Object Bucket Claim . 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: 'USD{BUCKET_NAME}' credentials: accessKeyId: 'USD{AWS_ACCESS_KEY_ID}' secretAccessKey: 'USD{AWS_SECRET_ACCESS_KEY}' endpoint: 'https://USD{BUCKET_HOST}' region: 'USD{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 your 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: 'USD{BUCKET_NAME}' credentials: accessKeyId: 'USD{AWS_ACCESS_KEY_ID}' secretAccessKey: 'USD{AWS_SECRET_ACCESS_KEY}' endpoint: 'https://USD{BUCKET_HOST}' region: 'USD{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 USDREPOSITORY_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: Install the npx package to run techdocs-cli using the following command: Install the techdocs-cli tool using the following command: Install the mkdocs plugins using the following command: 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: Set the necessary authentication environment variables for your cloud storage provider. 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 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: USD{{ secrets.TECHDOCS_S3_BUCKET_NAME }} AWS_ACCESS_KEY_ID: USD{{ secrets.AWS_ACCESS_KEY_ID }} AWS_SECRET_ACCESS_KEY: USD{{ secrets.AWS_SECRET_ACCESS_KEY }} AWS_REGION: USD{{ 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 USDTECHDOCS_S3_BUCKET_NAME --entity USDENTITY_NAMESPACE/USDENTITY_KIND/USDENTITY_NAME
apiVersion: objectbucket.io/v1alpha1 kind: ObjectBucketClaim metadata: name: <rhdh_bucket_claim_name> spec: generateBucketName: <rhdh_bucket_claim_name> storageClassName: openshift-storage.noobaa.io upstream: backstage: extraEnvVarsSecrets: - <rhdh_bucket_claim_name> extraEnvVarsCM: - <rhdh_bucket_claim_name> 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: 'USD{BUCKET_NAME}' credentials: accessKeyId: 'USD{AWS_ACCESS_KEY_ID}' secretAccessKey: 'USD{AWS_SECRET_ACCESS_KEY}' endpoint: 'https://USD{BUCKET_HOST}' region: 'USD{BUCKET_REGION}' s3ForcePathStyle: true type: awsS3 apiVersion: objectbucket.io/v1alpha1 kind: Backstage metadata: name: <name> spec: application: extraEnvs: configMaps: - name: <rhdh_bucket_claim_name> secrets: - name: <rhdh_bucket_claim_name> 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: 'USD{BUCKET_NAME}' credentials: accessKeyId: 'USD{AWS_ACCESS_KEY_ID}' secretAccessKey: 'USD{AWS_SECRET_ACCESS_KEY}' endpoint: 'https://USD{BUCKET_HOST}' region: 'USD{BUCKET_REGION}' s3ForcePathStyle: true type: awsS3 Prepare REPOSITORY_URL='https://github.com/org/repo' git clone USDREPOSITORY_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> git clone <https://path/to/docs-repository/> npm install -g npx npm install -g @techdocs/cli pip install "mkdocs-techdocs-core==1.*" npx @techdocs/cli generate --no-docker --source-dir <path_to_repo> --output-dir ./site npx @techdocs/cli publish --publisher-type <awsS3|googleGcs> --storage-name <bucket/container> --entity <namespace/kind/name> --directory ./site 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: USD{{ secrets.TECHDOCS_S3_BUCKET_NAME }} AWS_ACCESS_KEY_ID: USD{{ secrets.AWS_ACCESS_KEY_ID }} AWS_SECRET_ACCESS_KEY: USD{{ secrets.AWS_SECRET_ACCESS_KEY }} AWS_REGION: USD{{ 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 USDTECHDOCS_S3_BUCKET_NAME --entity USDENTITY_NAMESPACE/USDENTITY_KIND/USDENTITY_NAME