6.2. 配置 CI/CD 以生成和发布 TechDocs 站点
xmlrpc 从云存储桶（如 OpenShift Data Foundation）读取静态生成的文档文件。文档站点在与包含文档文件的存储库关联的 CI/CD 工作流上生成。您可以使用 HEKETI -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 配置为生成 HEKETI，请完成以下步骤：
使用以下命令安装
npx软件包以运行 HEKETI-cli：npm install -g npx
使用以下命令安装
HEKETI-cli工具：npm install -g @techdocs/cli
使用以下命令安装
mkdocs插件：pip install "mkdocs-techdocs-core==1.*"
使用以下命令生成 HEKETI 站点：
npx @techdocs/cli generate --no-docker --source-dir <path_to_repo> --output-dir ./site
其中 <
path_to_repo> 是用来克隆存储库的文件路径中的位置。
6.2.3. 发布 TechDocs 网站
流程
要发布您的 HEKETI 网站，请完成以下步骤：
- 为您的云存储供应商设置必要的身份验证环境变量。
使用以下命令发布您的 HEKETI ：
npx @techdocs/cli publish --publisher-type <awsS3|googleGcs> --storage-name <bucket/container> --entity <namespace/kind/name> --directory ./site
在软件模板中添加
.github/workflows/wagon.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
