本文主要是介绍swift生成文档工具-jazzy的使用教程，希望对大家解决编程问题提供一定的参考价值，需要的开发者们随着小编来一起学习吧！
Jazzy 介绍
jazzy是一个命令行实用程序，可为Swift或Objective-C生成文档，输出风格和官方文档匹配(也可以自定义模板)，如下图所示
要求
1、支持Xcode和SPM项目
2、建议在macOS上运行
安装
建议使用下面指令
sudo gem install jazzy -n /usr/local/bin --verbose
错误使用命令
gem install jazz
sudo gem install jazzy
sudo gem install jazzy --verbose
提示错误如下
ERROR: While executing gem ... (Gem::FilePermissionError)You don't have write permissions for the /usr/bin directory.
使用
从命令行运行jazzy。运行jazzy -h以获取其他选项的列表。
如果您的Swift模块是第一个要构建的模块，并且在运行时可以正常构建
如果xcodebuild或swift构建没有项目根目录的任何参数，则
只从项目的根开始运行爵士乐（不带任何参数）
也成功！
如果Jazzy为错误的模块生成文档，则使用–module告诉它哪个
一个你想要的。如果这样做没有帮助，并且您使用的是Xcode，请尝试传递
例如，xcodebuild的额外参数
爵士乐–build-tool-arguments -scheme，MyScheme，-target，MyTarget。
您可以在配置文件中为项目的文档设置选项，
.jazzy.yaml默认情况下。有关以下内容的详细说明和详尽列表
所有可用选项，运行jazzy --help config。
具备以下特性：
生成与Apple官方参考文档匹配的源代码文档
支持标准的Objective-C和Swift文档注释语法
利用现代HTML模板（Moustache）
利用Clang AST和SourceKit的强大功能和准确性
对Dash文档集的支持
支持Swift和Objective-C
文档注释的前提是有规范的注释
安装
终端运行
sudo brew install jazzy
1
基本使用
支持的文档标记
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
1
2
3
4
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
1
Swift文档权限控制
默认输出的 Swift 文档控制权限为 open 和 public,我么可以通过 --min-acl(access control list)来修改输出文档权限。可选参数internal、private和fileprivate。这个是和 Swift 的控制权限一致。
使用示例
jazzy --min-acl internal //internal 及以上的文档注释都可以输出
1
排除和包含文件
支持通配符
–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
1
基本配置
基本信息配置
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 命名官方约定和建议。
这篇关于swift生成文档工具-jazzy的使用教程的文章就介绍到这儿，希望我们推荐的文章对编程师们有所帮助！
