# JazzyDocumentGenerator

**Repository Path**: Sven001/JazzyDocumentGenerator

## Basic Information

- **Project Name**: JazzyDocumentGenerator
- **Description**: 文档生成器 Jazzy 使用练习，以及jazzy.yaml 配置
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-08-18
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align=center>  Jazzy 文档生成器使用 </p>

## 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](https://mustache.github.io/)）
- 利用[Clang AST](https://clang.llvm.org/docs/IntroductionToTheClangAST.html)和[SourceKit](https://www.jpsim.com/uncovering-sourcekit)的强大功能和准确性
- 对Dash文档集的支持
- 支持Swift和Objective-C

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

## 安装

终端运行

```shell
sudo brew install jazzy
```



## 基本使用

### 支持的文档标记

**Swift**

支持苹果官方 Swift 文档的基本文档注释，markdown 注释，[官方参考](https://developer.apple.com/library/archive/documentation/Xcode/Reference/xcode_markup_formatting_ref/MarkupSyntax.html#//apple_ref/doc/uid/TP40016497-CH105-SW1)， 可以参考[Cocoa 代码注释与文档生成 -- 掘金.土土 Edmond 木](https://juejin.im/post/6844904191526191118)方便易读

**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 文档创建命令

```shell
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

```shell
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` 文档命令

```shell
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 合并。

示例

```shell
# 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 样式

```shell
jazzy --theme jony
```

### Swift文档权限控制

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

使用示例

```shell
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](https://github.com/ReSwift)使用了 Jazzy 创建[文档](https://reswift.github.io/ReSwift/)，且实现了自定义目录和自定义 Html 模板(具体可以查看项目的 [.jazzy.json配置](https://github.com/ReSwift/ReSwift/blob/master/.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](https://github.com/ReSwift/ReSwift/blob/master/.jazzy.json) 文件

[示例项目](https://gitee.com/Sven001/JazzyDocumentGenerator.git)

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

```shell
touch .jazzy.yaml
```

基本配置

```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） 和 文件目录。

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

```



### 自定义Html模板

Jazzy 提供 默认三个模板，[apple](https://realm.io/docs/swift/latest/api/)、[fullwidth](https://reduxkit.github.io/ReduxKit/)、[jony](https://harshilshah.github.io/IGListKit/) 但是都有一个问题，不能一下就看见属性和方法的解释，需要点击展开详情。不如 [ReSwift](https://reswift.github.io/ReSwift/master/about-reswift.html) 的文档来得直接

待完成。。。

## 参考

[jazzy -- github.realm](https://github.com/realm/jazzy)

[利用 Jazzy + SourceKitten 生成多依赖的在线文档 -- 掘金.土土 Edmond 木](https://juejin.im/post/6844904197524029453)

[Cocoa 代码注释与文档生成 -- 掘金.土土 Edmond 木](https://juejin.im/post/6844904191526191118)：介绍文档规范，可作为平时编码规范。

[文档标记格式指南 -- 苹果官网](https://developer.apple.com/library/archive/documentation/Xcode/Reference/xcode_markup_formatting_ref/index.html#//apple_ref/doc/uid/TP40016497-CH2-SW1)

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

[Swift API 设计准则](https://swift.org/documentation/api-design-guidelines/) 对 API 命名官方约定和建议。