跳到内容

发布 workflow

部署文档网站

官方 Workflow 文档位于 https://square.ac.cn/workflow。网站内容包含三个部分：

  1. Markdown 文档：位于 docs/ 文件夹中，包含一组手工编写的 Markdown 文件，用于记录高级概念。使用静态网站生成器 mkdocs（带有 Material 主题）将 Markdown 转换为静态、样式化的 HTML。
  2. Kotlin API 参考：嵌入在 Kotlin 源文件中的 Kdoc 通过 Dokka 转换为 GitHub 风格的 Markdown，然后包含在静态生成的网站中。
  3. Swift API 参考：来自 Swift 文件的标记注释通过 Sourcedocs 转换为 Markdown，然后包含在静态生成的网站中。

注意：每当推送版本标签时，文档网站会自动构建和部署。只有当您想在本地处理网站时，才需要执行这些步骤。

设置网站生成器

如果您已经完成了此步骤，可以直接跳到下面的 将网站部署到生产环境。

Kotlin: Dokka

Dokka 作为 Gradle 插件运行，因此您需要能够使用 Gradle 构建 Kotlin 源码，仅此而已。要手动生成文档，运行

cd kotlin
./gradlew dokka

Swift: Sourcedocs

Sourcedocs 从 Swift 文件生成 Markdown 网站。要运行它，您需要 Ruby、rubygems、bundler (2.x)、Xcode 10.2+、CocoaPods，当然还有 Sourcedocs 本身。假设您已经设置了 Xcode、Ruby 和 rubygems，请安装其余的依赖项

gem install bundler cocoapods
brew install sourcedocs

您还需要检出 Swift 仓库

git clone https://github.com/square/workflow-swift.git
cd workflow-swift

然后在运行 Sourcedocs 之前生成一个 Xcode 项目

cd Samples/SampleApp/
bundle exec pod install
# If this is your first time running CocoaPods, that will fail and you'll need to run this instead:
#bundle exec pod install --repo-update

您可以手动生成文档以验证一切正常工作，运行

#cd Samples/SampleApp/
sourcedocs generate -- -scheme Workflow -workspace SampleApp.xcworkspace
sourcedocs generate -- -scheme WorkflowUI -workspace SampleApp.xcworkspace
sourcedocs generate -- -scheme WorkflowTesting -workspace SampleApp.xcworkspace

请注意，目前 sourcedocs 仅支持 Xcode 10，如果您使用 Xcode 11 运行它，可能会看到有关 Catalyst 的错误，并且只会生成空的 README 文件。

mkdocs

Mkdocs 是用 Python 编写的，所以要运行它，您需要 Python 3 和 pip。假设它们已经设置好，运行

pip install -r requirements.txt

手动生成网站，使用

mkdocs build

在处理文档文件时，您可以在本地运行网站，使用

mkdocs serve

将网站部署到生产环境

注意：每当推送版本标签时，文档网站都会通过 Github Workflow 自动构建和部署。只有当您想手动发布网站时，才需要执行这些步骤。

在正式部署网站之前，您需要在环境变量中导出我们的 Google Analytics 密钥，以便将其添加到 HTML 中。从项目维护者那里获取密钥，然后将以下内容添加到您的 .bashrc 文件中并重新加载它

export WORKFLOW_GOOGLE_ANALYTICS_KEY=UA-__________-1

现在您可以发布网站了！只需选择一个要部署的标签或 SHA，然后运行

./deploy_website.sh TAG_OR_SHA
# For example:
#./deploy_website.sh v0.18.0

这将把仓库克隆到一个临时目录，检出正确的 SHA，构建 Kotlin 和 Swift API 文档，生成 HTML，然后将新生成的内容推送到 GitHub 上的 gh-pages 分支。

验证 Markdown

由于我们所有的高级文档都以 Markdown 格式编写，我们在 CI 中运行一个 linter 以确保格式一致。Lint 错误会导致您的 PR 构建失败，因此要在本地运行，请安装 markdownlint

gem install mdl

使用 lint_docs.sh 运行 linter

./lint_docs.sh

规则可以通过编辑 .markdownlint.rb 进行配置。

Kotlin 注意事项

开发

要构建当前版本并将其安装到您的本地 Maven 仓库 (~/.m2)，运行

./gradlew clean installArchives

部署

配置

为了将 artifact 部署到 Maven 仓库，您需要在您的私有 Gradle 属性文件 (~/.gradle/gradle.properties) 中设置 4 个属性

RELEASE_REPOSITORY_URL=<url of release repository>
SNAPSHOT_REPOSITORY_URL=<url of snapshot repository
SONATYPE_NEXUS_USERNAME=<username>
SONATYPE_NEXUS_PASSWORD=<password>

快照发布

仔细检查 gradle.properties 是否正确包含 -SNAPSHOT 后缀，然后像发布生产版本一样将快照 artifact 上传到 Sonatype

./gradlew clean build && ./gradlew uploadArchives --no-parallel --no-daemon

您可以访问 https://oss.sonatype.org/content/repositories/snapshots/com/squareup/workflow/ 来验证 artifact 是否可用。