6.2. TechDocs サイトを生成して公開するための CI/CD の設定

TechDocs は、OpenShift Data Foundation などのクラウドストレージバケットから静的に生成されたドキュメントファイルを読み取ります。ドキュメントサイトは、ドキュメントファイルを含むリポジトリーに関連付けられた CI/CD ワークフローで生成されます。techdocs-cli CLI ツールを使用して、CI でドキュメントを生成し、クラウドストレージに公開できます。

次の例を使用して、TechDocs 公開用のスクリプトを作成できます。

# 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>

TechDocs ワークフローは、ユーザーがドキュメントファイルを含むリポジトリーに変更を加えたときに CI を開始します。docs/ ディレクトリーまたは mkdocs.yml 内のファイルが変更されたときにのみワークフローを開始するように設定できます。

6.2.1. CI 用のリポジトリーの準備

CI の最初のステップは、作業ディレクトリーにドキュメントソースリポジトリーを複製することです。

手順

作業ディレクトリーにドキュメントソースリポジトリーを複製するには、次のコマンドを入力します。
```
git clone <https://path/to/docs-repository/>
```

6.2.2. TechDocs サイトの生成

手順

技術ドキュメントを生成するように CI/CD を設定するには、次の手順を実行します。

次のコマンドを使用して、npx パッケージをインストールし、techdocs-cli を実行します。
```
npm install -g npx
```
次のコマンドを使用して techdocs-cli ツールをインストールします。
```
npm install -g @techdocs/cli
```
次のコマンドを使用して、mkdocs プラグインをインストールします。
```
pip install "mkdocs-techdocs-core==1.*"
```
次のコマンドを使用して、TechDocs サイトを生成します。
```
npx @techdocs/cli generate --no-docker --source-dir <path_to_repo> --output-dir ./site
```
<path_to_repo> は、リポジトリーを複製するために使用したファイルパス内の場所です。

6.2.3. TechDocs サイトの公開

手順

TechDocs サイトを公開するには、次の手順を実行します。

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

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

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

ソフトウェアテンプレートに .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

6.2. TechDocs サイトを生成して公開するための CI/CD の設定

6.2.1. CI 用のリポジトリーの準備

6.2.2. TechDocs サイトの生成

6.2.3. TechDocs サイトの公開

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

多様性を受け入れるオープンソースの強化

会社概要

Red Hat legal and privacy links

Red Hat legal and privacy links