提升 Xcode 中 DocC 文档的质量

♪低音音乐播放♪ ♪ 比翠丝马加良斯：嗨 我是比翠丝 我是文档团队的 人机界面设计师 我和我同事杰克将要介绍 如何在Xcode中改进你的DocC文档 和过去比起来 现在我们能更轻易地 写入和分享很棒的文档 今年 我们为你的Swift框架 将文档直接整合到Xcode 13中 在本次课程中 我们要来增强 我们建立的框架的文档 SlothCreator 你可以使用SlothCreator 对你在自然界中发现的树懒进行编目 并创造出新的、可爱的虚拟树懒 要让我们在这个框架下现有的文档 变得更好 我们会介绍在Xcode 13中 有哪些文档页面类型 可以使用 以及如何选择最适合你的内容的 如何编排你的API顺序 来介绍你的框架 和扩展如何能让你 更灵活地写入你的文档 我会先从新的Xcode性能开始 文档页面类型 Xcode 13有一个全新的性能 叫做“文档目录” 它可以让你建立三种你能在文档窗口 或是在网络上检视的页面类型 参照、文章和教程 每个项目都是独一无二的 而且各自有不同的需求 不过能拥有好几种文档通常是好事 参照会在你的函数库中 提供关于个别API简明而深入的信息 它能让你新增文字叙述 编码片段和不同符号之间的关系 这是你的文档的骨干 文章是没有固定格式内容的页面 它们很适合用来 说明框架如何运作的重点 以及解释如何完成特定的任务 它们通常会连结不同符号之间的点 教程是对于使用你框架的项目的 逐步解说 通过实际应用它来认识 符号的结合如何共同运作 是很棒的事 不同熟练程度的框架采用者 都可以从教程中受惠 不过值得注意的是 它也是非常适合初学者使用的格式 在本次课程中 我们会聚焦在文章上面 要了解参照和教程的信息 请参考其他WWDC的相关课程 在我开始增强我的 SlothCreator文档前 我要先来看看文档窗口有什么新内容 现在 你们可以看到 所有的Apple技术 以及在浏览器中 看到你们自己的文档 现在 我要查看我的 SlothCreator文档 目前的状态 我在Xcode中开启了SlothCreator Swift套件 我要点“产品” 然后点“建立文档” 来建立我的文档窗口 滑动来检视我的SlothCreator 框架文档 我看到我所有的符号 都已经有参照了 这很棒 然而 假设我从一个从来没用过 这个框架的人的角度 要来使用这个页面 我很难第一眼就知道它是做什么的 我可以用顶层文章来描绘出大方向 顶层文章有一句简明的摘要 一段概述 里面有像是图像 或是编码片段这些内容 以及一个在最下方的 要旨段落 上面有你想要强调的符号 要新增文章 我必须以文档目录来设定我的项目 文档目录是在Xcode浏览器中的文件 那里面包含我所有的文档文件 而且 它让我写入新的页面类型 这让大家一看就可以快速存取文档 并且让我更容易在我的 例行工作流程中 排列文档的优先顺序 要做这件事 我先在SlothCreator的 来源目录上按右键 这里面包含我们SlothCreator 目标的来源 然后选“新增文件” 接着我会往下滑这个清单 直到我找到文档目录 我会根据我的框架目标来命名 SlothCreator 当我建立文档目录时 Xcode会给我一个顶层文章 我会同时在项目浏览器和标记语法中 将它重新命名为“SlothCreator” 现在 让我们开始进入文章 你要用标记语法写入文章 首先 我要加入一个摘要 它会用一句话来描述我的框架 是做什么的 接着 我会在概述标题下 增加更详尽的信息来描述 SlothCreator的主要功能 研究、关怀和可视化 最后 我要增加一张图像 让开发者能够看一眼就知道 他们看的内容是什么 我会建议新增2x分辨率的图像 而且是兼容深色模式的 或是具有深色模式替代图像 记得要替你的文件 加入适当的命名规则 首先 你的文件的名字：“sloth” 接着 如果你的图像是在深色模式下 用波浪号以及“dark”这个字 然后用@2x来描述比例系数 最后是你的图像格式 这里我们用的是.png 现在已经确认我有适当的图像大小 并且正确命名了 我要打开访达 然后把资产拖到我的文档目录的 资源文件夹

接下来 我要将图像新增到 文章的标记语法 我先加上一个惊叹号 然后是在中括号之间的描述 来存取我的图像 最后 是括号中的文件名称 你可能已经注意到 我没有输入“@2x”或是“~dark” 那是因为Xcode会自动选取图像 所以我只要输入图像本身的名字 就可以了 好的 我完成我的顶层文章了 让我来建立我的文档 看看它长什么样子 我会点“产品” 然后再选一次“建立文档” 来叫出我的文档窗口 太好了 SlothCreator有一个 清楚的顶层摘要 一个概述 上面有更多关于 这个框架是做什么的脉络 以及一张图像 让人可以看一眼 就知道这个框架的核心概念 现在 即便从来没用过 SlothCreator的人 也可以很快速地大致理解 这个框架是做什么的 通过提供如何开始SlothCreator的 可操作的第一步 我可以让这个文档更好 一份任务文章可能可以帮上忙 我已经事先准备好任务文章 接着我要开启访达 把它拖到我的SlothCreator 文档目录中

这份文章的目的是教大家 如何创建和关怀一只树懒 它是这个框架的核心元素 就结构来说 它和顶层文章很类似 两个类型都能包含文字、图像 和编码片段 最大的差别是在内容里面 要看到这些差异 我要再一次 建立我的文档 我要选取“产品”和“建立文档”

然后 在我的文档窗口浏览器中 我要选取“树懒入门” 太好了 这段文章 通过描述树懒的属性和特征 提供了更多关于如何建立树懒的脉络 它也给出如何关怀树懒 和建构适当栖地的可操作步骤 这能让大家更快速地 采用SlothCreator 回顾一下 到目前为止 我谈到所有大家可以建立的 不同类型的文档 以及每一种的用途 我介绍了Xcode 13的新性能 “文档目录” 它能让你把所有的文档文件 放到同一个位置 以及建立新的文档类型 而且我用它建立两份文章 通过在我的文档中给出更多脉络 和深入特定的任务来增强我的文档 要写出那些文章 我使用标记语法 以及我们现在在文档中支持的新文件 现在我要把时间交给杰克 他会告诉大家如何通过编排你的符号 和建立文档扩展 让你的文档更好 杰克劳伦斯：谢谢 比翠丝 那些文章看起来很棒 现在我们已经加入新的页面了 我可以用另一个方法 指导大家使用框架 刚才比翠丝建立了一个 有SlothCreator概述的框架页面 在页面的下方 DocC编译器会自动建立一个要旨段落 上面有全部Sloth框架的文档 这是一很好的开始 不过我想我们还能再改良它 让我们往回退一步 想一下你想要说的故事 SlothCreator API分成 三个主要的类别 研究和创造树懒 关怀你的树懒的健康和幸福 以及在树懒的栖息地观察它 我可以用这三个类别 来编排SlothCreator中的文档页面 这些是用于框架的顶层页面 首先 除了最重要的页面外 其他的我都先放到旁边去 我待会可以在另一个页面下 编排支持类型 例如速度和颜色 接着 我会以SlothCreator的特征 为中心 把剩下的页面分成小组 最后 我会将小组和页面 从最低到最高等来分类 这个新的编排看起来平易近人多了 而且对特定性能感兴趣的框架采用者 马上就知道要看哪里 现在我们要替框架更新文档 来使用这些主题 我把SlothCreator项目 和建立好的文档打开 编译器会自动在每个页面加上 有预设类别的要旨段落 不过我可以用一些额外的标记语法 来定制它 稍早之前 比翠丝建立了一个 包含框架文章的 文档目录 在项目浏览器中 我要选取在文档目录中的 SlothCreator标记语法文件 模板中已经包含要让我填入的 要旨段落 从“本质”开始 我会在第三层标题中更新小组标题 接着我会加入一系列 要包含在小组内的连结 我会从“入门”文章开始 还有树懒的类型 要连结到文章上 我会用没有扩展名的文件名称 使用文档URL格式 要连结到一个符号上 我会在名字的前后都加上两个重音符 利用我刚刚建立的类别 我也要将其他所有的文档页面 编排到小组中 现在我要重新建立 看一下这些改变 在“产品”选单中 我要选取“建立文档”来重新建立 文档建立好了 可是我看到DocC产生一个诊断 看起来我在这里拼错一个连结 让我们用自动完成来处理它 这样我可以很肯定它是对的 现在我要再次重新建立文档 从“产品”选单 看看我是否 把所有问题都解决了

太好了 没有其他警告 在文档窗口中的框架页面上 我们新的“入门”文章 是所有人会看到的第一个标题 接着是根据复杂度排列的 SlothCreator的主题 在左边的文档浏览器 也根据每一页的要旨段落做出更新 所以我可以很快找到我想看的页面 现在让我们来检视如何编排你的文档 你所有的页面都会自动编排 而你可以用要旨段落来改造 要建立一个要旨段落 在第二层标题新增一个题目 然后 以第三层标题新增一个小组 底下有一连串你想在目前页面中编排 并且通往其他页面的连结 你可以把要旨段落加到任何文章上 以及任何容器符号 像是类别、结构、枚举或是协议 当你在为你的框架 编排文档时 考虑最重要的性能和主题 以及哪些API开发者会共同使用它 来建立app 将辅助页面搬移到你的主要文档下 来增加焦点和清晰度 先从基本的开始 然后再一步步导入复杂度 既然我已经自定义了 框架页面上的小组 我想要编排在SlothCreator中的 所有文档 包含类型和它们的成员 文档扩展让我可以灵活地 选择我要如何替我的API写入文档 我可以直接在我的来源编码 加上自定义标题 但是我认为要长时间检视和维护 将这个额外的文档放在独立的文件中 会比较简单 我可以用一个文档扩展来做那件事 首先 我建立一个新的标记语法文件 我利用标题中链接语法 把它连结到API上 接下来 为了改进在我来源编码中的 焦点和清晰度 我会把像是摘要和讨论 这些主要内容留在编码中 并且取出要旨段落

当DocC被建立出来的时候 它会将每个来源注释 和相对应的文档扩展 合并成一个文档页面 通过这些扩展 可以很简单地写入和检视文档 改善框架产生的界面 并且提供更好的 文档阅读体验 现在 我要加入一个文档扩展 替SlothCreator强化文档 首先 在做出任何更动前 我会先看一下树懒页面 我有树懒类型的文档注释 也有建立好的文档 我在来源编码中写入的文档 看起来很棒 不过要旨段落可以再改进 而且我可以在文档扩展中做这件事 在项目浏览器中 我会在文档目录上点右键 来新增一个文件 在模板选择器中 我要选扩展文件模板 并且把它命名为“Sloth” 接着我会用标题中的连结 把扩展文件连结到树懒类型 我需要在URL中包含模块的名称

这可能看起来很熟悉 因为刚刚我同事比翠丝 用这个语法 来建立顶层框架文章 接着 我会在要旨段落中 加入一些自定义的小组 最后 我要重新建立 从产品>建立文档 来检查结果

我在来源编码写入的内容 依旧在最上面 而我在文档文件中建立的要旨段落 被加到那后面 当我在浏览器中拉开页面 浏览器也已经更新了 我和比翠丝做的更动都完成了 我们准备好要跟全世界分享它们了 在Xcode中 文档看起来很棒 只要下载了Swift套件 任何人都可以建立它 我也可以用浏览器中的“输出”按钮 来输出一个文件 让你不用下载或建立整个Swift套件 就可以使用这个文件 在Xcode中浏览文档 如果我希望所有人都可以存取它 我甚至可以在网络上发布文档 大家可以查看此相关课程来了解更多 现在 我们回顾一下 如何替你的Swift框架 改进文档 首先 建立文章来介绍你的框架 以及解释你的API是如何共同运作 接下来 在你的文档编排成小组来改善导航 最后 在文档扩展文件中 将深度和细节加到你的 API参考说明上 如果你想要更进一步 你可以从下面两个相关课程中 学习如何发布到网络上 并且通过教程引导读者一步步来进行 Xcode 13是文档的重大更新 我们很期待看到大家发布的内容 谢谢你们的收看！ ♪