Jazzy 文件生成器使用

jazzy 文件生成器使用

jazzy 是乙個命令列實用程式，可以為 swift 或者 objective-c 生成文件，輸出風格和官方文件匹配(也可以自定義模板)

如果是 swift和 objective-c 混合專案生成文件，需要通過 sourcekitten 生成分別生成 swift和 objective-c 然後再利用 jazzy 生成文件，詳情參考 github readme 中 mixed objective-c/swift部分。

具備以下特性：

支援標準的objective-c和swift文件注釋語法

利用現代html模板（moustache）

利用clang ast和sourcekit的強大功能和準確性

對das**檔集的支援

支援swift和objective-c

文件注釋的前提是有規範的注釋

終端執行

sudo brew install jazzy

swift

objective-c

僅僅支援以下關鍵字

文件交叉鏈結

swift

進入專案終端路徑,以下是 real 文件建立命令

jazzy \ --clean \ --author realm \ --author_url \ --github_url \ --github-file-prefix /tree/v0.96.2 \ --module-version 0.96.2 \ --build-tool-arguments -scheme,realmswift \ --module realmswift \ --root-url /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 就稍微麻煩一點，需要新增以下引數

以下是用於生成afnetworking文件命令

jazzy \ --objc \ --author afnetworking \ --author_url \ --github_url \ --github-file-prefix /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

fullwidthexample:

jonyexample:

比如使用 jony 樣式

jazzy --theme jony

預設輸出的 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排除檔案

請注意，該--include選項在--exclude選項之前應用

包含文件注釋的宣告:nodoc:將從文件中排除。

除了可以通過終端命令配置，還可以在專案下建立jazzy 的配置檔案，更方便和有記錄性的配置文件要求。

reswift使用了 jazzy 建立文件，且實現了自定義目錄和自定義 html 模板(具體可以檢視專案的 .jazzy.json配置)

配置檔案支援 json 和 yaml, 這裡我們使用 yaml, 執行jazzy會預設檢查，如果目錄下有.jazzy.yaml配置，則會自動該配置。

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

建議使用 json 配置，不用學習 yaml 語法。可以參考 reswift 的 jazzy.json 檔案

示例專案

進入專案目錄下，建立配置檔案

touch .jazzy.yaml

基本配置

# 基本資訊配置 author : sven #author_url: "" # 作者位址鏈結 module : jazzydocument # 需要和專案一致 theme module_version : 1.0.0 # 文件版本號 output :"./apidocs" # 文件輸出位置 min_acl : internal # 許可權控制 #readme: # readme 路徑（路徑需要引號） documentation :"*/docs/*.md" # markdown文件位置 # 忽略檔案 exclude:-

-"*/scenedelegate.swift"

為了專案的可讀性，我們可以使用自定義目錄，新增 markdown（需要指定 documentation）和檔案目錄。

# 自定義目錄 custom_categories:- name :"使用指導" children:- "開始" -"安裝" -"結束" -name :"列舉" children:- "diration" -name :"類" children:- "myclass"

-"viewcontroller"

待完成。。。

jazzy – github.realm

cocoa **注釋與文件生成 – 掘金.土土 edmond 木：介紹文件規範，可作為平時編碼規範。

swift api 設計準則對 api 命名官方約定和建議。

擴充套件蘋果官方的 docc，可參考docc: 未曾設想的蘋果文件

Jazzy 文件生成器使用

Sandcastle幫助文件生成器使用介紹

python生成器使用方式

keras 資料生成器使用小結

Jazzy 文件生成器使用

Sandcastle幫助文件生成器使用介紹

python生成器使用方式

keras 資料生成器使用小結

相關推薦