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

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

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

Prepare
Install @techdocs/cli, mkdocs and mkdocs plugins
Generate
Publish

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

Copy to Clipboard

Toggle word wrap

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

6.2.1. CI 用のリポジトリーの準備
リンクのコピー

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

手順

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

6.2.2. TechDocs サイトの生成
リンクのコピー

手順

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

次のコマンドを使用して、npx パッケージをインストールし、techdocs-cli を実行します。
```
npm install -g npx
```
```
npm install -g npx
```
Copy to Clipboard Toggle word wrap
次のコマンドを使用して techdocs-cli ツールをインストールします。
```
npm install -g @techdocs/cli
```
```
npm install -g @techdocs/cli
```
Copy to Clipboard Toggle word wrap
次のコマンドを使用して、mkdocs プラグインをインストールします。
```
pip install "mkdocs-techdocs-core==1.*"
```
```
pip install "mkdocs-techdocs-core==1.*"
```
Copy to Clipboard Toggle word wrap
次のコマンドを使用して、TechDocs サイトを生成します。
```
npx @techdocs/cli generate --no-docker --source-dir <path_to_repo> --output-dir ./site
```
```
npx @techdocs/cli generate --no-docker --source-dir <path_to_repo> --output-dir ./site
```
Copy to Clipboard Toggle word wrap
<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

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

Copy to Clipboard

Toggle word wrap

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

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

Toggle word wrap

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

6.2.1. CI 用のリポジトリーの準備
リンクのコピー

6.2.2. TechDocs サイトの生成
リンクのコピー

6.2.3. TechDocs サイトの公開
リンクのコピー

詳細情報

試用、購入および販売

コミュニティー

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

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

会社概要

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

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

6.2.1. CI 用のリポジトリーの準備リンクのコピーリンクがクリップボードにコピーされました!

6.2.2. TechDocs サイトの生成リンクのコピーリンクがクリップボードにコピーされました!

6.2.3. TechDocs サイトの公開リンクのコピーリンクがクリップボードにコピーされました!

詳細情報

試用、購入および販売

コミュニティー

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

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

会社概要

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

6.2.1. CI 用のリポジトリーの準備
リンクのコピー

6.2.2. TechDocs サイトの生成
リンクのコピー

6.2.3. TechDocs サイトの公開
リンクのコピー