Red Hat Developer Hub の TechDocs

1. 次のコマンドを使用して、npx パッケージをインストールし、techdocs-cli を実行します。

   npm install -g npx

   Copy to Clipboard

2. 次のコマンドを使用して techdocs-cli ツールをインストールします。

   npm install -g @techdocs/cli

   Copy to Clipboard

3. 次のコマンドを使用して、mkdocs プラグインをインストールします。

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

   Copy to Clipboard

4. 次のコマンドを使用して、techdocs サイトを生成します。

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

   Copy to Clipboard

   <path_to_repo> は、リポジトリーを複製するために使用したファイルパス内の場所です。

1. クラウドストレージプロバイダーに必要な認証環境変数を設定します。

2. 次のコマンドを使用して、技術ドキュメントを公開します。

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

   Copy to Clipboard

3. ソフトウェアテンプレートに .github/workflows/techdocs.yml ファイルを追加します。以下に例を示します。

   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

   Copy to Clipboard

手順

1. OpenShift Container Platform Web コンソールの Developer パースペクティブから、ConfigMaps > Create ConfigMap をクリックします。
2. Create ConfigMap ページで、Configure via フィールドの YAML view オプションを選択します。

3. 新しく作成した ConfigMap に、デフォルトの backstage-plugin-techdocs-module-addons-contrib パッケージ設定を追加します。以下に例を示します。

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: dynamic-plugins-rhdh
   data:
     dynamic-plugins.yaml: |
       includes:
         - dynamic-plugins.default.yaml
       plugins:
         - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
           disabled: false
           pluginConfig:
             dynamicPlugins:
               frontend:
                 backstage.plugin-techdocs-module-addons-contrib:
                   techdocsAddons:
                     - importName: ReportIssue

   Copy to Clipboard

4. ConfigMap の techdocsAddons セクションで、指定したプラグインパッケージから追加する外部 TechDocs アドオンごとに importName: <external_techdocs_add-on> を追加します。以下に例を示します。

   kind: ConfigMap
   apiVersion: v1
   metadata:
     name: dynamic-plugins-rhdh
   data:
     dynamic-plugins.yaml: |
       includes:
         - dynamic-plugins.default.yaml
       plugins:
         - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
           disabled: false
           pluginConfig:
             dynamicPlugins:
               frontend:
                 backstage.plugin-techdocs-module-addons-contrib:
                   techdocsAddons:
                     - importName: ReportIssue
                     - importName: <external_techdocs_add-on>

   Copy to Clipboard

   ここでは、以下のようになります。

   <external_techdocs_add-on>

   インストールする外部 TechDocs アドオン (TextSize や LightBox など) を指定します。

5. Create をクリックします。
6. Web コンソールのナビゲーションメニューで、Topology をクリックします。
7. 使用する Red Hat Developer Hub インスタンスのオーバーフローメニューをクリックし、Edit Backstage を選択して、Red Hat Developer Hub インスタンスの YAML ビューを読み込みます。

8. Backstage CR で、dynamicPluginsConfigMapName: <dynamic_plugins_configmap> というキーと値のペアを追加します。以下に例を示します。

   apiVersion: rhdh.redhat.com/v1alpha3
   kind: Backstage
   metadata:
     name: my-rhdh
   spec:
     application:
   # ...
       dynamicPluginsConfigMapName: _<dynamic_plugins_configmap>_
   # ...

   Copy to Clipboard

   ここでは、以下のようになります。

   <dynamic_plugins_configmap>

   Red Hat Developer Hub インスタンスの動的プラグイン ConfigMap の名前を指定します (例: dynamic-plugins-rhdh)。

9. Save をクリックします。
10. Web コンソールのナビゲーションメニューで、Topology をクリックし、Red Hat Developer Hub の Pod が起動するまで待ちます。
11. Open URL アイコンをクリックして、新しい設定変更を適用した Red Hat Developer Hub プラットフォームの使用を開始します。

手順

1. Helm チャートを使用した動的プラグインのインストール に示されているように、Helm チャートで、動的プラグインをインストールするために必要な global.dynamic パラメーターを追加します。

   注記

   デフォルト設定には dynamic-plugins.default.yaml ファイルが含まれています。このファイルには、デフォルトで有効か無効かに関係なく、Red Hat Developer Hub にプリインストールされているすべての動的プラグイン (TechDocs アドオンを含む) が含まれています。

2. Helm チャートで、デフォルトの backstage-plugin-techdocs-module-addons-contrib パッケージ設定を追加します。以下に例を示します。

   global:
     dynamic:
       plugins:
         - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
           disabled: false
           pluginConfig:
             dynamicPlugins:
               frontend:
                 backstage.plugin-techdocs-module-addons-contrib:
                   techdocsAddons:
                     - importName: ReportIssue

   Copy to Clipboard

3. Helm チャートの techdocsAddons セクションで、指定したプラグインパッケージから追加する外部 TechDocs アドオンごとに importName: <external_techdocs_add-on> を追加します。以下に例を示します。

   global:
     dynamic:
       plugins:
         - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
           disabled: false
           pluginConfig:
             dynamicPlugins:
               frontend:
                 backstage.plugin-techdocs-module-addons-contrib:
                   techdocsAddons:
                     - importName: ReportIssue
                     - importName: <external_techdocs_add-on>

   Copy to Clipboard

   ここでは、以下のようになります。

   <external_techdocs_add-on>

   インストールする外部 TechDocs アドオン (TextSize や LightBox など) を指定します。

手順

1. 次のコマンドを入力して、サードパーティーのアドオンをインポートするために使用するサードパーティーのプラグインをインストールします。

   yarn install

   Copy to Clipboard
2. 使用するサードパーティーの TechDocs アドオンのソースコードを取得します。

3. 次のコマンドを使用して、TechDocs アドオンを動的プラグインとしてエクスポートします。

   npx @janus-idp/cli@latest package export-dynamic-plugin

   Copy to Clipboard
   注記

   @latest タグは、最新の機能および修正と互換性のある最新バージョンの @janus-idp/cli パッケージを取得します。Red Hat Developer Hub のバージョンと互換性のあるバージョンを使用してください。

4. サードパーティーの TechDocs アドオンを動的プラグインとしてパッケージ化するために、プラグインが保存されているルートディレクトリー (dist-dynamic ディレクトリーではない) に移動し、--tag オプションを指定して npx コマンドを実行し、イメージ名とタグを指定します。以下に例を示します。

   npx @janus-idp/cli@latest package package-dynamic-plugins --tag quay.io/<user_name>/<techdocs_add-on_image>:latest

   Copy to Clipboard
   注記

   package-dynamic-plugins コマンドの出力に、dynamic-plugin-config.yaml ファイルで使用するプラグインへのファイルパスが表示されます。

5. サードパーティーの TechDocs アドオンを Quay リポジトリーに公開するために、お使いの仮想化ツールに応じて次のいずれかのコマンドを使用して、イメージをレジストリーにプッシュします。

   • podman を使用するには、次のコマンドを入力します。

     podman push quay.io/<user_name>/<techdocs_add-on_image>:latest

     Copy to Clipboard

   • docker を使用するには、次のコマンドを入力します。

     docker push quay.io/<user_name>/<techdocs_add-on_image>:latest

     Copy to Clipboard

6. dynamic-plugins.yaml ファイルを開き、サードパーティーの TechDocs アドオンの設定を表示または変更します。以下に例を示します。

   plugins:
         - package: oci://quay.io/<user_name>/<techdocs_add-on_image>:latest!<techdocs_add-on_package>
           disabled: false
           pluginConfig:
             dynamicPlugins:
               frontend:
                <techdocs_add-on_package>
                   techdocsAddons:
                     - importName: <third-party_add-on_name>
                      config:
                         props:
                          <techdocs_add-on_property_key>: <techdocs_add-on_property_value>

   Copy to Clipboard

   以下は、

   <user_name>

   Quay ユーザー名または組織名を指定します。

   <techdocs_add-on_image>

   使用するサードパーティーアドオンのイメージの名前を指定します (例: mermaid)。

   <techdocs_add-on_package>

   パッケージを指定します (例: backstage-plugin-techdocs-addon-mermaid)。

   <third-party_add-on_name>

   使用するサードパーティーアドオンの名前を指定します (例: Mermaid)。

   <techdocs_add-on_property_key>

   サードパーティーアドオンに渡すことができるカスタムプロパティーの名前 (例: themeVariables) を指定します。プロパティーは各アドオンに固有です。1 つのアドオンに対して複数のプロパティーをリストできます。

   <techdocs_add-on_property_value>

   サードパーティーアドオンのプロパティーキーの値を指定します (例: lineColor: #000000)。

手順

1. OpenShift Container Platform Web コンソールの Developer パースペクティブから、ConfigMaps をクリックします。
2. ConfigMaps ページで、削除する TechDocs アドオンが含まれている ConfigMap をクリックします。
3. Configure via フィールドで YAML view オプションを選択します。

4. ConfigMap の plugins セクションで、TechDocs アドオンを無効にするか削除するかに応じて、次のいずれかの操作を実行します。

   • 特定のプラグインパッケージ内の TechDocs アドオンをすべて一時的に無効にするには、disabled フィールドの値を true に変更します。以下に例を示します。

     kind: ConfigMap
     apiVersion: v1
     metadata:
       name: dynamic-plugins-rhdh
     data:
       dynamic-plugins.yaml: |
         includes:
           - dynamic-plugins.default.yaml
         plugins:
           - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
             disabled: true
             pluginConfig:
               dynamicPlugins:
                 frontend:
                   backstage.plugin-techdocs-module-addons-contrib:
                     techdocsAddons:
                       - importName: ReportIssue
                       - importName: <external_techdocs_add-on>

     Copy to Clipboard

     ここでは、以下のようになります。

     <external_techdocs_add-on>

     削除する外部 TechDocs アドオン (例: TextSize) を指定します。

   • Red Hat Developer Hub インスタンスから 1 つ以上の TechDocs アドオンを削除するには、ConfigMap の techdocsAddons セクションから、削除する各外部 TechDocs アドオンの importName: <external_techdocs_add-on> を削除します。以下に例を示します。

     kind: ConfigMap
     apiVersion: v1
     metadata:
       name: dynamic-plugins-rhdh
     data:
       dynamic-plugins.yaml: |
         includes:
           - dynamic-plugins.default.yaml
         plugins:
           - package: ./dynamic-plugins/dist/backstage-plugin-techdocs-module-addons-contrib
             disabled: false
             pluginConfig:
               dynamicPlugins:
                 frontend:
                   backstage.plugin-techdocs-module-addons-contrib:
                     techdocsAddons:
                       - importName: ReportIssue
                       - importName: <external_techdocs_add-on>

     Copy to Clipboard

     ここでは、以下のようになります。

     <external_techdocs_add-on>

     削除する外部 TechDocs アドオン (例: TextSize) を指定します。

5. Save をクリックします。
6. Web コンソールのナビゲーションメニューで、Topology をクリックし、Red Hat Developer Hub の Pod が起動するまで待ちます。
7. Open URL アイコンをクリックして、新しい設定変更を適用した Red Hat Developer Hub プラットフォームの使用を開始します。

手順

1. TechDocs ドキュメントで、イシューとして報告するテキストを強調表示します。
2. ReportIssue ボックス内のテキスト (例: Open new GitHub issue) をクリックします。

3. リポジトリーの新しいイシューページから、報告するイシューをテンプレートを使用して作成します。

   注記

   デフォルトのイシュータイトルは Documentation feedback: <highlighted_text> です。<highlighted_text> は、TechDocs ドキュメントで強調表示したテキストです。

   イシューの説明では、<highlighted_text> が The highlighted text フィールドのデフォルト値になります。

手順

1. TechDocs ヘッダーで、Settings アイコンをクリックします。

2. スライドスケールを使用して、ドキュメントのテキストのサイズを調整します。

   注記
   • デフォルトのテキストサイズは 100% です。
   • 最小テキストサイズは 90% です。
   • 最大テキストサイズは 150% です。

手順

1. TechDocs ドキュメントで、ライトボックスで表示する画像をクリックします。

2. ライトボックスでは、次のいずれかの操作を実行できます。

   • 画像をクリックするかスクロールして拡大または縮小します。
   • 矢印をクリックして画像を切り替えます。