Jazzy 文档生成器使用

Jazzy 文档生成器使用

Jazzy 简介

jazzy 是一个命令行实用程序，可以为 Swift 或者 Objective-C 生成文档，输出风格和官方文档匹配(也可以自定义模板)

如果是 Swift和 Objective-C 混合项目生成文档，需要通过 SourceKitten 生成分别生成 swift和 Objective-C 然后再利用 jazzy 生成文档，详情参考 github README 中 Mixed Objective-C/Swift部分。

具备以下特性：

• 生成与Apple官方参考文档匹配的源代码文档
• 支持标准的Objective-C和Swift文档注释语法
• 利用现代HTML模板（Moustache）
• 利用Clang AST和SourceKit的强大功能和准确性
• 对Dash文档集的支持
• 支持Swift和Objective-C

文档注释的前提是有规范的注释

安装

终端运行

sudo brew install jazzy

基本使用

支持的文档标记

Swift

支持苹果官方 Swift 文档的基本文档注释，markdown 注释，官方参考， 可以参考Cocoa 代码注释与文档生成 – 掘金.土土 Edmond 木方便易读

Objective-C

仅仅支持以下关键字

• @param
• @return
• @warning
• @see
• @note

文档交叉链接

• `MyClass`-的文档可以链接到MyClass。
• MyClass.method（param1 -该方法文档的链接。
• MyClass.method（…）-同一件事的快捷方式语法。
• method（…）-链接到method同一类中另一个方法或属性的文档的快捷方式语法。
• `[MyClass method1]`-到Objective-C方法的链接。
• `-[MyClass method2：param1]-到另一个Objective-C方法的链接。

快速生成文档

Swift

进入项目终端路径,以下是 Real 文档创建命令

jazzy \
  --clean \
  --author Realm \
  --author_url https://realm.io \
  --github_url https://github.com/realm/realm-cocoa \
  --github-file-prefix https://github.com/realm/realm-cocoa/tree/v0.96.2 \
  --module-version 0.96.2 \
  --build-tool-arguments -scheme,RealmSwift \
  --module RealmSwift \
  --root-url https://realm.io/docs/swift/0.96.2/api/ \
  --output docs/swift_output \
  --theme docs/themes

使用 Swift Package Manager

jazzy \
  --module DeckOfPlayingCards \
  --swift-build-tool spm \
  --build-tool-arguments -Xswiftc,-swift-version,-Xswiftc,5

Objective-C

Objective-C 就稍微麻烦一点，需要添加以下参数

• --objc
• --umbrella-header ... : 暴露的.h 文件路径
• --framework-root ...
• --sdk [iphone|watch|appletv][os|simulator]|macosx (可选, 平台选择， 默认是 macosx)
• --hide-declarations [objc|swift] (optional, hides the selected language declarations)

以下是用于生成 AFNetworking 文档命令

jazzy \
  --objc \
  --author AFNetworking \
  --author_url http://afnetworking.com \
  --github_url https://github.com/AFNetworking/AFNetworking \
  --github-file-prefix https://github.com/AFNetworking/AFNetworking/tree/2.6.2 \
  --module-version 2.6.2 \
  --umbrella-header AFNetworking/AFNetworking.h \
  --framework-root . \
  --module AFNetworking

混编项目

需要借助 SourceKitten 来分别生成 Swift 和 Objective-C 的 json文档， 然后在通过 jazzy 合并。

示例

# Generate Swift SourceKitten output
sourcekitten doc -- -workspace MyProject.xcworkspace -scheme MyScheme > swiftDoc.json

# Generate Objective-C SourceKitten output
sourcekitten doc --objc $(pwd)/MyProject/MyProject.h \
      -- -x objective-c  -isysroot $(xcrun --show-sdk-path --sdk iphonesimulator) \
      -I $(pwd) -fmodules > objcDoc.json

# Feed both outputs to Jazzy as a comma-separated list
jazzy --sourcekitten-sourcefile swiftDoc.json,objcDoc.json

文档主题样式

jazzy提供三中主题：apple默认类似苹果官方文档主题，fullwidth全屏幕样式和 jony,效果示例如下

• apple example: https://realm.io/docs/swift/latest/api/
• fullwidth example: https://reduxkit.github.io/ReduxKit/
• jony example: https://harshilshah.github.io/IGListKit/

比如使用 jony 样式

jazzy --theme jony

Swift文档权限控制

默认输出的 Swift 文档控制权限为 open 和 public,我么可以通过 --min-acl(access control list)来修改输出文档权限。可选参数internal、private和fileprivate。这个是和 Swift 的控制权限一致。

使用示例

jazzy --min-acl internal //internal 及以上的文档注释都可以输出

排除和包含文件

支持通配符

--include包含文件

jazzy --include=/Users/fred/project/Sources/Secret.swift -包含特定文件

--exclude 排除文件

• jazzy --exclude=/*/Internal*-排除所有文件与开头的名称内部 任何文件的任何目录下有一个名称开头的内部。
• jazzy --exclude=Impl1/*,Impl2/*-排除当前目录中Impl1和 Impl2目录下的所有文件。

请注意，该--include选项在--exclude选项之前应用

• jazzy --include=/*/Internal* --exclude=Impl1/*,Impl2/*-包括有与名称开头的所有文件内，并开始与一个名称的任何目录下的任何文件 内部，除外对于那些目录下Impl1和Impl2在当前目录中找到

包含文档注释的声明:nodoc:将从文档中排除。

高级使用

除了可以通过终端命令配置，还可以在项目下创建jazzy 的配置文件，更方便和有记录性的配置文档要求。

ReSwift使用了 Jazzy 创建文档，且实现了自定义目录和自定义 Html 模板(具体可以查看项目的 .jazzy.json配置)

配置.jazzy.yaml配置文件

配置文件支持 json 和 yaml, 这里我们使用 yaml, 执行 jazzy会默认检查，如果目录下有 .jazzy.yaml 配置，则会自动该配置。

json 配置格式 .yaml.json 执行jazzy 需要指定 config 路径 jazzy --config .yaml.json

也可以使用 在线 json 转 yaml 来互转。

建议使用 json 配置，不用学习 yaml 语法。可以参考 ReSwift 的 jazzy.json 文件

示例项目

进入项目目录下，创建配置文件

touch .jazzy.yaml

基本配置

# 基本信息配置
author: Sven
#author_url: "" # 作者地址链接
module: JazzyDocument # 需要和项目一致
theme: apple # 样式 apple| fullwidth |
module_version: 1.0.0 # 文档版本号
output: "./APIDocs" # 文档输出位置
min_acl: internal # 权限控制
#readme: # README 路径（路径需要引号）

documentation: "*/Docs/*.md" # markdown文档位置

# 忽略文件
exclude:
  - "*/AppDelegate.swift"
  - "*/SceneDelegate.swift"
  

自定义目录

为了项目的可读性，我们可以使用自定义目录，添加 markdown（需要指定 documentation） 和 文件目录。

# 自定义目录
custom_categories:
- name: "使用指导"
  children:
  - "开始"
  - "安装"
  - "结束"
- name:  "枚举"
  children:
  - "Diration"
- name:  "类"
  children:
  - "MyClass"
  - "ViewController"

自定义Html模板

Jazzy 提供 默认三个模板，apple、fullwidth、jony 但是都有一个问题，不能一下就看见属性和方法的解释，需要点击展开详情。不如 ReSwift 的文档来得直接

待完成。。。

参考

jazzy – github.realm

利用 Jazzy + SourceKitten 生成多依赖的在线文档 – 掘金.土土 Edmond 木

Cocoa 代码注释与文档生成 – 掘金.土土 Edmond 木：介绍文档规范，可作为平时编码规范。

文档标记格式指南 – 苹果官网

ReSwift – github: 基于 jazzy 生成的 swift 文档，配置了.jazzy.json配置文件，自定义目录，自定义 html 模板（非常喜欢这个模板，不需要一个一个属性和方法的点开就可以看到介绍）

Swift API 设计准则 对 API 命名官方约定和建议。