Skip to main content

配置 CI/CD 以生成和发布 TechDocs 站点

在建议的部署设置TechDocs 会从云存储桶(GCS、AWS S3 等)中读取静态生成的文档文件。 文档站点会在与包含文档文件的存储库相关联的 CI/CD 工作流中生成。 本文档介绍了在 CI 上生成文档并发布到云存储所需的步骤，其中使用了技术支持.

这里的步骤针对所有类型的 CI 提供商(GitHub Actions、CircleCI、Jenkins 等)。 为简单起见，这里还将提供针对单个提供商的特定工具(例如 GitHub Actions runner、CircleCI orb 等)。

下面的说明摘要如下

# This is an example script

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

就是这样！

看一看技术支持以获取完整的命令参考、详细信息和选项。

步骤​

1.设置工作流程​

当包含文档文件的版本库中有任何更改时，TechDocs 工作流程应在 CI 上触发。 您可以具体配置工作流程，使其仅在以下情况下触发docs/目录或mkdocs.yml被更改。

2.​

CI 的第一步是在工作目录中克隆文档源代码库。 这几乎是大多数 CI 工作流程的第一步。

在 GitHub 操作上，您可以添加一个步骤

使用：actions@checkout@v3`。.

在 CircleCI 上，您可以添加一个特殊的结账步骤。

最终，我们将尝试git clone <https://path/to/docs-repository/>.

3.​

安装npx用于跑步techdocs-cli或者使用npm install -g @techdocs/cli.

我们将使用techdocs-cli generate 生成命令。

npx @techdocs/cli generate --no-docker --source-dir PATH_TO_REPO --output-dir ./site

PATH_TO_REPO应该是上述准备步骤克隆版本库的文件路径中的位置。

4.​

根据您的云存储提供商(AWS、Google Cloud 或 Azure)，设置必要的身份验证环境变量。

然后运行技术支持发布指挥。

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

在此工作流程中建立的更新后的 TechDocs 网站现在可以由Backstage应用程序中的 TechDocs 插件提供服务。

示例：GitHub Actions CI 和 AWS S3​

以下是一个使用 GitHub Actions CI 和 AWS S3 存储的工作流程示例。 您可以使用任何 CI 和任何其他TechDocs 支持的云存储提供商.

添加一个.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'

      # the 2 steps below can be removed if you aren't using plantuml in your documentation
      - name: setup java
        uses: actions/setup-java@v3
        with:
          distribution: 'zulu'
          java-version: '11'
      - name: download, validate, install plantuml and its dependencies
        run: |
          curl -o plantuml.jar -L http://sourceforge.net/projects/plantuml/files/plantuml.1.2021.4.jar/download
          echo "be498123d20eaea95a94b174d770ef94adfdca18 plantuml.jar" | sha1sum -c -
          mv plantuml.jar /opt/plantuml.jar
          mkdir -p "$HOME/.local/bin"
          echo $'#!/bin/sh\n\njava -jar '/opt/plantuml.jar' ${@}' >> "$HOME/.local/bin/plantuml"
          chmod +x "$HOME/.local/bin/plantuml"
          echo "$HOME/.local/bin" >> $GITHUB_PATH
          sudo apt-get install -y graphviz

      - 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

当新仓库搭建好脚手架或提交了新的文档更新时，GitHub Action 工作流程就会发布 TechDocs 网站，您可以在 Backstage 应用程序中查看该网站。