托管和自动化 DocC 文档

了解如何轻松地在线托管 Swift 文件包和框架 DocC 文档。我们还将带您了解如何配置网页服务器来托管生成的 DocC 存档，并帮助您学习使用 xcodebuild 工具来自动生成文档并保持网页内容同步及最新。

资源

相关视频

WWDC21

下载

大家好我叫大卫是Apple文档工具团队的一名工程师本讲座中您会学习如何将DocC文档存储到服务器以及如何自动化文档建立首先我会讲解如何在Xcode里构建文档以及你如何将构建好的文档档案存储到一个服务器上接下来我会深入讲解如何构建一套文档以及如何自动构建文档

本讲座中我会向您展示一个叫树懒生成器的项目是我同事和我一起开发的

我们创建了一个网页帮助人们入门这里令我们兴奋的是 Xcode中新的文档功能可以为我们的文档构建出一个可以存储到网站的版本这会让新手入门变得更加简单我们看看如何完成这些吧

Xcode 13里新的文档功能使为Swift框架资源库和包构建文档变得非常简单您可以不需任何设置就开始使用它在后面再添加额外的物料来扩展您的文档

操作非常简单从开发者文档窗口导出您的文档就行了

导出的文档档案可以与别人共享他人可以导入Xcode并阅读该文档或将该文档档案存储在线上

若您想了解更多Xcode中文档功能的详情以及如何在文档中使用自己的符号我的同事维多利亚和伊森在“Xcode中DocC文档入门”讲座中会为您详细讲解本节课的第二部分中我会为您讲解如何在命令行上自动构建文档但是眼下我还是先使用从Xcode里导出文档档案来存储在我们服务器上

文档档案本身就像一个容器它可以容纳所有的数据兼具在Xcode中读取文档和在线存储文档的功能

它是按照一个单页面 Vue.js网页App来构建的它可以用来渲染您的参考文档和文章也可以渲染富文本的交互性教程

要存储文档档案服务器需要处理两种不同的请求一种是对文档和教程页面的请求其请求的URL开头是 /documentation或/tutorials 另一种是对其他文件和数据的请求其经由网页App加载请求的URL会在文档档案中寻找与相对文件的路径匹配的某个文件

这里我们看一个例子这是一条构成一个页面的请求看看服务器是如何应答的

当一位开发者要读取您存储的文档浏览器就会请求一个页面若请求以/documentation 或/tutorials开始然后服务器就会以index.html文件应答该文件位于文档档案中

该文件引用文档档案里的 CSS和JavaScript 浏览器会请求加载网页App余下的部分

当加载完成后网页App会请求该页面的内容以及任何它引用的图片或媒体文件

两类文件不管是index.html引用的文件还是网页App加载的内容和媒体使用的请求URL都要匹配文档档案中的文件夹结构

现在您已了解了服务器如何应答收到的请求我们现在去实例中看看应该有很多人已经拥有可以存储网页的服务器本项目中我们使用Apache服务器但您可以使用任何允许自定义路由的服务器

这就是我们树懒生成器的网页我们已经添加上了“阅读文档”按钮就在屏幕中央介绍语的下面但是这个按钮暂时还并不能工作我们来修复这个问题

我已经将文档档案复制到了我们存储网页的目录并添加了一个后缀名为.htaccess的空白文件但是我还未设置任何路由

这里我需要添加2条路由规则一条给文档和教程页面一条给其他文件和数据

在第一条规则下我想要匹配的模式是找到任何开头第一部分是 documentation 或tutorials的URL

任何匹配该模式的请求都进行重定路由转给文档档案里的 index.html文件

最后设立一个旗标（flag）来结束本条规则当请求匹配上了本条规则时就停止评估

第二条规则中我会更明确地描述待匹配模式由于我们的网页也存储在服务器上我们不希望针对网页的请求被重定路由到文档档案中的文件上

若我们看一下文档档案内部可以看到里面有很多顶层文件和文件夹我可以根据模式进行匹配所以现在我将添加一个匹配全部这些的模式

本例中请求的URL 是文档档案中某个文件的相对路径于是我要把该请求重定路由到匹配的模式上但是要用SlothCreator.doccarchive 预修复一下和之前一样这里也要添加一个旗标来终止规则评估

现在若我重新加载网页点击文档链接可以看到我们的网页和文档就都存储在服务器上了

树懒生成器主页将重要的符号分组成一个个话题它们与更高级的任务相关

每个分组的符号下又细分为更特定的话题

DocC是内建的且设计简洁它可以很好地与多种项目相结合有了它为您的项目构建美观且优雅的文档变得非常简单就像这份树懒生成器文档一样现在我们网站上已经存储了一份文档接下来我们学一下如何自动构建和更新文档档案文件为此我们要编写一份脚本它会调用codebuild 脚本就绪之后每当有新的变动时我就可以运行它这样一来存储的文档就能时刻保持更新了 Xcode 13加入了一项新功能您可以通过xcodebuild的新动作docbuild 在命令行上构建文档

当您在Xcode或xcodebuild里构建文档它就像一个标准程序可以构建文档

在构建过程中 Swift编译器收集关于所有公共符号它们之间的关系还有源代码内文档注释的详细信息将这些作为一个名为符号图表的文件传递给文档编译器来生成一个文档档案其中包含在Xcode中读取文档和在线存储它所有的必需信息若目标拥有一个相关的文档编目含有你的项目所需的额外的文章媒体或教程那么文档编译器生成文档档案时将会通过符号信息来编译全部这些内容

若您想了解关于文档编目的更多详情请观看 “在Xcode中改进您的DocC文档” 我的同事碧雅和杰克会为您讲解不同类型文档以及如何在其间进行取舍希望能为开发者提供了解您项目的最好方式

构建文档不仅仅应用于您的目标若您的目标的运行还依赖其他Swift框架资源库或者包那么同样的过程也会应用到它们全体这样一来您项目所有相关的文档就汇聚在一处了

由于我想要通过脚本来自动构建和更新存储在服务器里的文档那么命令行上的xcodebuild 就是完成此举的绝佳工具

xcodebuild里新引入的docbuild动作其工作方式和默认的“构建”动作一样但是它还能构建文档

就像“构建”动作一样你要将想要构建的scheme 以及它所属的项目或工作区传送进来

您也可以从包含您项目工作区或Swift包的目录里调用xcodebuild 仅将scheme传递给它根据您的项目和scheme 您可能会想要传递其他的旗标例如sdk、目的地或配置以期对您的项目如何构建进行自定义

这不是必需的但是可以让人们更轻松地跟上我会设定一个自定义的 derivedDataPath 它指定了构建出来的产品和文档会被写在哪里

在构建完成之后我可以找到所有以.doccarchive为文件扩展名的文档档案全都复制到另一个位置或另一台机器

我们到实例中看一下

这是之前我们存储在服务器里的文档它将相关的符号分组成一个个话题这样便于开发者针对某特定任务找到核心类型

在我们构建了这个版本之后我的同事在Essentials小节添加了一些新的文章和教程所以现在我就要编写一份自动化脚本来构建最新版的文档并升级我们的网站

如您所见要构建文档我们要调用xcodebuild的 docbuild动作更新网站则需要找到文档档案并复制到网站所存储的目录里去

我已经知道需要将什么scheme传送过去因为在Xcode的Scheme选择器里可以看到它们是一样的若我没打开Xcode 则可以在命令行上运行xcodebuild -list 将所有可用scheme都列出来

同样地自定义的derivedDataPath 不是必须的但是它能更方便的追踪文档在哪里编写和找到

当构建完成后我可以找到所有的文档档案一一复制到我们网站存储的目录里

这些完成后我就可以运行脚本了

现在若我刷新一下在Essential小节里您就可以看到新添加的文章和教程了

经过最近一次的修改我们的文档看起来更完整了新手面对树懒生成器可以更好地上手起步无论他们是喜欢文字教程

或是教程中分步指导

现在更新我们存在服务里的文档只需简单的运行脚本即可若我们在持续集成服务器上将它作为一个 post-merge挂钩来运行那我们就可以确保服务器上的文档永远是最新版的

现在总结一下本讲座中的知识点您可以将文档档案共享或存储于在线服务器上以为您框架的使用者提供优质的文档体验即使他们没有在Xcode中打开它在命令行上构建文档使您可以将文档包含到您的自动化工作流程中

若您想学习更多DocC文档的知识 “Xcode下DocC文档入门” 是个不错的入门讲座它对Xcode中的文档功能进行了详细讲解

“在Xcode中改进您的DocC文档” 讲座则更深入的讲解如何通过DocC编目对文档进行增强 “用DocC构建交互型教程”讲座详细讲解了如何将您的想法构建出来为您的项目创建优秀的教程感谢您的观看 [音乐]

4:49 - Custom routing in a .htaccess file

# Enable custom routing.
RewriteEngine On

# Route documentation and tutorial pages.
RewriteRule ^(documentation|tutorials)\/.*$ SlothCreator.doccarchive/index.html [L]

# Route files within the documentation archive.
RewriteRule ^(css|js|data|images|downloads|favicon\.ico|favicon\.svg|img|theme-settings\.json|videos)\/.*$ SlothCreator.doccarchive/$0 [L]

9:17 - Build documentation on the command line

# Build documentation for the project.
xcodebuild docbuild                    \
  -scheme "SlothCreator"               \
  -derivedDataPath MyDerivedDataFolder
  
# Find all the built documentation archives
# to copy them to another location.
find MyDerivedDataFolder               \
  -name "*.doccarchive"

9:18 - Build and update the hosted documentation

#!/bin/sh

# Build the SlothCreator documentation.
xcodebuild docbuild                  \
  -scheme "SlothCreator"             \
  -derivedDataPath MyDerivedDataPath
  
# Copy the documentation archive to ~/www where we
# host the SlothCreator website and documentation.
find MyDerivedDataPath               \
  -name "*.doccarchive"              \
  -exec cp -R {} ~/www \;

正在查找特定内容？在上方输入一个主题，就能直接跳转到相应的精彩内容。