Swift-DocC 的新功能

Swift-DocC 的新功能

和我们一起了解 Swift-DocC 的精彩更新，学习如何为您自己的项目编写与共享文档。我们将探索 Swift-DocC 导航的改进，并分享为 App 目标及 Objective-C 代码编译文档的流程。我们还会介绍如何将您的内容直接发布到托管服务，如 GitHub Pages。

资源
相关视频

WWDC23
- 使用 Swift-DocC 创建丰富的文档
下载

♪ 柔和乐器演奏的嘻哈音乐 ♪ ♪ Franklin Schrans：您好我叫 Franklin 我是 Swift-DocC 团队的工程师我将与我的同事 Ethan 一起为您介绍 Xcode 14 中的 Swift-DocC 它装载了许多优秀的新工具用来帮助您创建更好的文档我们去年在 Xcode 13 中引入了 Swift-DocC 可以让您指导开发人员如何使用您的 Swift 框架使用 Swift-DocC 您可以编写全面的文档内容从单个 API 的参考文档到提供一起使用这些 API 的更高层次描述的概念性文章一直到引导用户完成任务的分步教程在今年发布的 Xcode 14 中 Swift-DocC 开启了全新的令人兴奋的工作流程我们很兴奋地告诉您现在除了文档框架现在 Swift-DocC 也支持 App 项目这样您就可以轻松地与您的团队协作您现在还可以使用 Swift-DocC 记录 Objective-C 语言和 C 语言 API 文档并允许您将所有 APIs 文档结合起来进行描述将您制作的内容发布到网站现在变得出乎意料的容易对于类似 GitHub Pages 的静态托管环境具有开箱即用的环境支持感谢功能强大的新导航侧边栏开发人员能够比以往任何时候都容易发现您的内容此外由于 Swift-DocC 现在是一个开源项目因此这些新特性是与开源社区密切合作开发的在本次讲座中我们将开启 Swift-DocC 旅程以及了解它在 Xcode 14 中开启的令人兴奋的全新工作流程首先我们将讨论在您的项目中如何与您的源代码内联并记录 API 然后我们会看看如何无缝地将您的内容发布到网站最后我们会研究网站上全新的导航侧边栏让我们先从编写文档开始好的文档对于任何软件项目都是必不可少的随着项目的发展描述其功能和设计概念非常重要以便于让开发者在参与工作时有一个坚实的参考点 Xcode 中的 Swift-DocC 为您提供创建出色文档所需的工具它使用的是与代码开发相同的工具在今年我们很高兴能将 Swift-DocC 扩展到 App 项目中去让我们深入了解一下我们需要编写一个软件这个软件是我和我的团队开发的软件名叫做 Slothy 其中包含 Swift 和 Objective-C 的程序源文件即使对于一个我还没有编写文档的全新项目您仍然可以打开 Project 菜单并选择 Build Documentation Xcode 打开会文档窗口您将看到 Swift-DocC 自动为您的 API 生成的根节点这为填补页面内容提供了一个很好的起点以便于帮助参与者导航项目那么让我们一步步的为该项目的开发者将这些内容变成一份丰富而完整的 App 构建指南一个成功的开始就是说明每个 API 是如何工作的然后使用文档目录提供更高级别的内容让我们从视图 SlothView 的内容描述开始为了让 Swift-DocC 可以识别这部分文档内容请在注释前加上三个斜杠然后为您的视图添加简明摘要在构建的文档页面中该内容将转换为文本显示在视图名称正下方的显著位置然后增加其他段落以添加更多详细信息此内容显示在页面的概述部分并且使用 Swift-DocC 链接语法会将针对 API 的引用转换为活动链接让您快速跳转到相关页面以便了解更多信息 DocC 甚至可以在您建立文档时校验这些了链接所以如果链接失效您就会收到一个警告信息最后如果您想为这个视图提供一段示例代码请使用 Markdown 代码块语法添加代码示例现在参与者对此视图的使用方法一目了然只需要几个步骤我的视图文档就可以为项目参与者提供更多的帮助接下来让我们为一个初始化程序编写文档和之前一样从写摘要开始对于初始化程序和方法模块最好单独描述每个参数您可以通过添加参数列表项来做到这一点简要说明每个参数的用处和意义注意在单独显示的参数部分中描述内容的显示方式现在让我们看一下使用 Objective-C 编写的 API 在这个项目中如何编写文档定义我们很高兴为您带来 Xcode 14 中的新功能使用 Swift-DocC 的综合工具来为 Objective-C 代码创建文档使用类似于您了解并喜爱的 Markdown 语法以及在 Xcode 源码编辑器中得到的升级和支持您现在可以将项目中所有 API 进行统一的组织和描述对于可以从 Swift 和 Objective-C 使用的代码页面会有一个小巧的语言切换显示在代码的浏览页面里点击视频下方的开发人员文档链接以查看更多细节现在让我们将它应用到我们的 Slothy 项目中我将针对 SLOSound 类及其初始化程序进行描述请注意因为这个类可以同时在 Swift 和 Objective-C 中使用 Xcode 会显示一个语言切换提示允许您切换到您正在使用语言的描述页面让我们使用与 Swift 语法相同的 Markdown 语法描述类和初始化程序太好了这看起来好多了我添加了一个摘要一个概述以及对于初始化程序的参数部分的描述至此对各个 API 的描述就结束了通过在源代码中编写一些文档注释参加我项目的开发人员将会更好的了解如何使用这些 API 现在让我们专注于为我们的 App 创建一个漂亮的顶级页面这是参与开发者将要看到的第一页所以我想提供一个很好的介绍以便于参与者了解 App 的功能以及如何参与项目要定义顶级页面首先添加一个文档目录请右键点击项目的源文件夹并选择 New File 然后选择 Documentation Catalog 文档目录可以补充您的源代码文档并包含其他 Markdown 文件和媒体 Xcode 会自动为 App 的顶级页面添加一个文件让我们来概述一下 App 的功能使用与源代码中文档注释相同的语法我添加了一个摘要一个概述以及甚至像图片一样的富文本内容太好了这样看起来更有吸引力了现在参与者一眼就知道我的 App 是关于什么的了就是这样我极大地改进了 App 的文档并给我的项目参与者提供了一个很好的参考点他们可以从顶级页面浏览项目的概览内容并跳转到每个 API 的详细信息页面现在我们已经了解了如何编写和构建文档是时候将其发布到网站了以便项目参与者可以轻松浏览它交给您了 Ethan Ethan Kusters：谢谢 Franklin 我们一直在以模块化方式开发 Slothy App 开发内容还有一个更普遍有效的 Swift 软件包这个软件包叫做 SlothCreator 我认为将 SlothCreator 发布给更广泛的受众是更好的以便其他开发人员在制作与 Sloth App 相关的 App 时可以用的上作为这项工作的一部分我想确定 SlothCreator 的文档很容易在网络上得到共享那么让我们来看看 Swift-DocC 的全新功能简易发布工作流程在 Xcode 中构建文档时 Swift-DocC 会生成一个包含文档的静态包此包称为 DocC 档案是您的文档的便携式容器您可以直接从 Xcode 的文档窗口导出并将其发送给同事他们只需双击档案文件就可以打开和浏览文档但 DocC 档案不仅仅是一个为了在 Xcode 中打开文档的便携式容器它还包含一个功能齐全的开箱即用网站在 Xcode14 中新增的 DocC 档案功能也与大多数 Web 服务器直接兼容这使得将您的文档发布到网络上比以往任何时候都容易在大多数情况下您只需通过拷贝您建立好的 DocC 档案内容复制到网络服务器的根目录来部署您的文档这也就意味着 DocC 档案现在与大多数托管服务兼容包括 GitHub Pages GitHub Pages 是一种流行的方式许多开发人员将他们的文档直接集成到 GitHub.com 中并且由于我们一直在 GitHub 上进行 SlothCreator 的源代码管理因此我们在那里发布文档也是有意义的如果您熟悉如何使用 GitHub Pages 您应该清楚与一般的 Web 服务器不同您的网站不会在 URL 的根路径中发布而是发布于一个特定的基本路径上在这种托管场景中您需要使用附加的构建设置来指定网站的基本路径以便生成兼容的 DocC 档案若要充分了解它是如何工作的以及为什么我们只需要在某些如在 GitHub Pages 的托管场景中需要此配置让我们来看看托管在您自己的域服务器上 DocC 档案的 URL 会是什么样子假设我们已有一个 Slothy App 的网站 slothy.example.com 我们希望将 SlothCreator 的文档作为该现有网站的一部分进行发布如果我们只获取 SlothCreator DocC 档案的内容并将其复制到我们网络服务器的根目录那么 SlothCreator 的参考文档的网站链接将会是 slothy.example.com/ documentation/slothcreator 任何 SlothCreator 包的教程都将位于邻近的 tutorials 路径上然而在这个案例里我们不会将文档发布到我们自己的域服务器取而代之的是将文档保存到我们的 GitHub 存储库中我们会将文档发布到 GitHub Pages 提供的域内当您为存储库创建 GitHub Pages 站点时该网站的 URL 并不是直接位于根路径下的而是位于一个与存储库名称相对应的基本路径下通常这类名称的表现类似于：您的用户名.github.io/您的存储库名任何参考和教程的文档路径都会附加在该基本路径之后因为此基本路径对于您的存储库来说是唯一的所以在构建用于发布到 GitHub Pages 的 DocC 档案之前告诉 Swift-DocC 发布路径是什么就非常重要这是在 Xcode 14 中针对此项目构建的新的配置设置配置后 DocC 档案的网络托管基本路径（DocC Archive Hosting Base Path）将会设置为您的 GitHub 存储库名称现在您已经为将来所有文档的构建做好了准备让我们看看这在实践中是如何工作的在这里我打开了 SlothCreator Swift 软件包 Franklin 早先将其作为 Slothy App 的依赖项向您展示过因为我们即将发布这个包以供更广泛的使用所以我将继续在 GitHub 页面上发布我们准备好的文档我将首先打开框架的项目设置通过将鼠标移动到 Xcode 的项目导航器并选择 SlothCreator 项接下来我需要选择 SlothCreator 标签然后打开 Build Settings 选项卡在这个案例中我正在寻找与 Swift-DocC 的相关设置所以让我们过滤 DocC 的内容现在我将设置 DocC Archive Hosting Base Path 设置我们存储库的名称为 sloth-creator 好的接下来让我们来构建文档我将鼠标移到 Product 菜单并选择 Build Documentation 当 Xcode 完成项目编译并为其生成文档后文档窗口将会打开这是 SlothCreator 文档的顶级页面让我们继续来导出它我将鼠标移到文档导航器的 SlothCreator 项目上接下来我将单击上下文菜单并选择 Export 我要把它导出到一个名为 docs 的目录这个目录在我的存储库的根目录中因为这就是我将文档网站发布到 Github Pages 的配置方式
现在我只需要提交并将我的更改推送到 GitHub 回到 Xcode 主窗口我将鼠标移到 Source Control 菜单并选择 Commit 我将选择包含文档内容的 docs 目录并写一个提交信息接着让我们推送更新内容
就是这样现在去看看发布的网站我将在 GitHub.com 上打开我的存储库
我已经在 README 文件中设置了一个指向文档站点的链接所以我只需点击它那么现在我们就到首页了太棒了我们为 SlothCreator 编写的文档可以在网络上轻松地访问我认为这对有兴趣在自己的项目中使用 SlothCreator 的人们来说真的很有帮助现在我们已经为 SlothCreator 部署了一次文档现在我非常想设置自动化部署以便于在存储库中的文档发生任何变化时自动发布由于我们将 SlothCreator 作为 Swift 软件包发布新的 Swift-DocC Swift Package Manager 插件在这里会有很大的帮助您可以在部署 Swift 软件包时使用 Swift-DocC 插件以便于真正简化构建文档的过程该插件的文档链接在视频下方我建议您看一看作为将文档自动化部署到 GitHub Pages 和其他托管服务时的一个很好的起点当然 Swift-DocC 仍然可以通过使用 xcodebuild docbuild 命令行接口为 Xcode 项目提供强大的命令行支持该功能是在 Xcode 13 中引入的关于如何使用 xcodebuild 命令自动化部署 GitHub Pages 的文档链接在视频下方我们很高兴今年可以在网上发布 Swift-DocC 的增强型浏览和导航体验让我们来看看新的导航侧栏如何帮助 SlothCreator 的文档读者探索框架所提供的功能我们回到了SlothCreator 的 GitHub Pages 站点在页面的左侧是新的导航侧边栏我将鼠标移动 CareSchedule 项目并通过单击三角形展开内容现在我可以看到页面就像 CareSchedule 的子节点已经被重新组织并显示了出来这甚至不用完全打开页面在本例中我希望的是直接跳转到类型的初始化器我可以继续在框架中导航打开其他项就像 FoodGenerator 和 SlothFood 这样直至最终打开树形页面当我在页面之间导航时导航侧边栏的状态保持不变并允许我跟踪我已经访问过的页面这允许对框架进行非常有效的探索这对我来说太有用了但是如果我已经熟悉 SlothCreator 框架并且正在寻找有关特定符号的信息该怎么办呢？新导航侧边栏底部的过滤器非常适合这个需求我想找到一个增强树懒能量等级的 API 我将鼠标移动到导航器的底部选择过滤器栏然后输入 energy 完美有关 energyLevel 属性的文档正是我想要的在 Xcode 14 中的 Swift-DocC 提供的新浏览体验可以把您的站点提升到一个新的水平我们很高兴您能尝试一下 Swift-DocC 在 Xcode 中的集成功能现在对所有项目的文档化提供了支持这包括您在 App 和使用框架中的 Objective-C 和 Swift 代码无论是打包为 Xcode 项目还是 Swift 软件包都是可用的 Xcode 14 生成的 DocC 档案可以立即与流行的托管服务兼容这也包括 GitHub Pages 这是分发文档的变革者可以把文档提供给更广泛受众最后 Swift-DocC 提供强大的网上全新导航体验导航侧边栏将解锁探索和查找您网站上文档的新方式了解更多关于新的 Swift-DocC 侧边栏的信息以及如何利用其功能最好地构建您的文档请查看讲座 Improve the discoverability of your Swift-DocC content 为了提高您的文档展示和部署水平请查看 Build interactive tutorials using DocC 讲座以便于了解如何构建分步导航教程帮助并引导开发者了解您的 App 或框架我们非常期待能看到您用 Xcode 14 编写和发布的所有文档谢谢收看 ♪

/// A view that displays a sloth.
///
/// This is the main view of ``SlothyApp``.
/// Create a sloth view by providing a binding to a sloth.
///
/// ```swift
/// @State private var sloth: Sloth
///
/// var body: some View {
///     SlothView(sloth: $sloth)
/// }
/// ```
struct SlothView: View {
    // ...
}

4:25 - Documenting an initializer

struct SlothView: View {
    /// Creates a view that displays the specified sloth.
    ///
    /// - Parameter sloth: The sloth the user will edit.
    init(sloth: Binding<Sloth>) {
				// ...
    }
}

5:24 - Documenting the SLOSound Objective-C class

/// A sound that can be played.
///
/// Use an instance of this type to play a sound
/// to the user in response to an action or
/// event.
@interface SLOSound : NSObject

/// Creates a sound given its name and path on
/// disk.
///
/// - Parameters:
///   - name: The name of the sound.
///   - filePath: The path to the sound file on disk.
- (id)initWithName:(NSString *)name
          filePath:(NSString *)filePath;

@end

6:48 - Documenting the top-level page for the Slothy app

# ``Slothy``

An app to create and care for custom sloths.

## Overview

Slothy is an iOS app that allows users to create and care for virtual sloths.

![An illustration displaying the UI for finding, creating, and taking care of a sloth in Slothy.](slothy.png)

The Slothy app project contains views to present Slothy's user interface, and utilities to play sounds as the user interacts with the app.

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

提交你查询的内容时出现错误。请检查互联网连接，然后再试一次。

资源

相关视频

WWDC23