Jazzy 사용법

Jazzy 사용법

Github Jazzy Site

Jazzy는 프로젝트 문서를 애플 Document 처럼 만들어주는 오픈 소스 유틸리티이다.
gem을 이용해서 다운로드 받고 프로젝트 폴더 루트에서 실행하면 된다.

Jazzy 설치하기

[sudo] gem install jazzy
Running xcodebuild
Parsing ...
building site
jam out ♪♫ to your fresh new docs in `docs`

기본 사용법

기본적으로 클래스와 public만 문서화가 되지만 
--min-acl 옵션으로 internal과 private, public 항목도 처리 가능하다.

원하는 클래스만 문서화되길 원한다면 직접 public으로 수정하는 것도 하나의 방법

• internal 옵션도 허용

--min-acl internal

• private 옵션 허용

--min-acl private 

• 문서화 되지 않은 클래스를 포함하지 않는다.

--skip-undocumented

• 기존 문서 제거하고 새로 만든다.

--clean

• 작성자 지정

--author 까칠코더

• 테마 설정 (기본 apple)

--theme fullwidth

예제 (swift 2.2, internal 옵션클래스만, 문서화 되지 않으면 제외)

jazzy --swift-version 2.2 --min-acl internal —-skip-undocumented

예제 문서 재생성, aaa.swift 제외

jazzy --swift-version 2.2 --min-acl internal —-skip-undocumented --exclude aaa/aaa.swift --clean

Realm 예제

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 \
  --xcodebuild-arguments -scheme,RealmSwift \
  --module RealmSwift \
  --root-url https://realm.io/docs/swift/0.96.2/api/ \
  --output docs/swift_output \
  --theme docs/themes

설정 옵션 도움말

jazzy --help config

• HTML 출력 폴더 지정
  -o, --output 폴더명(default : docs)

• 기존 HTML 출력 폴더 제거 
  -c, --[no-]clean

• Objective-C에 대한 문서 생성
  --[no-]objc

• Objective-C 프레임워크에 대해 Umbrella Header 경로 지정 (Swift클래스를 Objective-C에서 사용하기 위한 헤더파일로, 기본적으로 컴파일러가 알아서 만들어주는 헤더 [모듈명]-Swift.h) 
  --umbrella-header 경로

• Objective-C 프레임워크의 루트 경로 지정
  --framework-root 경로

• 코드를 빌드하기 위한 SDK (default : macosx)
  --sdk [iphone|watch|appletv][os|simulator]|macosx

• 소스 디렉토리나 상위 디렉토리에 위치한 설정 파일(.yaml 또는 .json) 지정 (default : .jazzy.yaml)
  --config 경로

• XCode 빌드시 인자값 사용 (default : [])
  -x, --xcodebuild-arguments arg1,arg2,…argN

• SourceKitten에서 만든 소스파일 지정 
  -s, --sourcekitten-sourcefile 파일 경로

• 소스가 들어있는 디렉토리 지정 
  --source-directory 폴더 경로

• 문서화에 제외할 파일과 디렉토리 (default : []) 콤마(,)사용시 공백 없이 사용
  -e, --exclude file1,file2,directory3,…fileN

• Swift 버젼 지정 
  --swift-version 버전

• 작성자 이름 
  -a, --author 작성자 이름

• 작성자 URL 
  -u, --author_url URL

• 문서 모듈 이름 
  -m, --module 모듈 이름

• 모듈 버젼 지정 (default : 1.0)
  --module-version 버젼

• 저작권 정보 (문서 하단에 표시됨)
  --copyright 저작권 정보

• markdown 도움말 파일 경로 
  --readme 파일 경로

• 사용가능한 문서와 일치하는 GLOB(??)
  --documentation GLOB

• 사용가능한 범주와 일치하는 GLOB(??)
  --abstract GLOB

• Pod 스팩
  --podspec 파일 경로

• 문서 아이콘 파일 지정 
  --docset-icon 파일 경로

• 생성된 문서에 대한 상대 경로 
  --docset-path 폴더 경로

• 문서가 저장될 루트 URL 
  -r, --root-url URL

• Dash XML URL
  -d, --dash_url URL

• Github 프로젝트 URL 
  -g, --github_url URL

• Github 프로젝트의 파일 prefix
  --github-file-prefix PREFIX

• 문서 생성 단계 건너뛰기
  --skip-documentation

• 문서 최소 접근 레벨 지정 (default : public)
  --min-acl [private | internal | public]

• 주석이 없는 항목은 문서화 하지 않기 
  --[no-]skip-undocumented

• 문서화 커버리지(X% 문서화) 표시 숨기기 
  --[no-]hide-documentation-coverage

• 사용자 정의 해더 ()에 들어갈 내용
  --head HTML코드

• 테마 디렉토리 설정 (default : apple)
  --theme [apple | fullwidth | DIRPATH]

• 기본 범주(Classes, Protocols, etc.)를 사용자 정의화 하기 (default : [])
  custom_categories 커스텀화

기존 프로젝트 참조
예제파일 : http://git.io/v4Bcp
.jazzy.yaml

module: Siesta
author: Bust Out Solutions
author_url: http://bustoutsolutions.com
github_url: https://github.com/bustoutsolutions/siesta
exclude: [Source/Support/Siesta-ObjC.swift, Source/Support/Deprecations.swift]

copyright: '© 2016 [Bust Out Solutions](http://bustoutsolutions.com) under [open source license](https://github.com/bustoutsolutions/siesta/blob/master/LICENSE).'

swift_version: 2.2

theme: fullwidth

custom_categories:
  - name: Resources
    children:
    - Service
    - Resource
    - Entity
    - Error
    - Configuration
    - ConfigurationPatternConvertible
    - TypedContentAccessors

  - name: Observing Resources
    children:
    - ResourceObserver
    - ResourceObserverClosure
    - ResourceEvent

  - name: Network Requests
    children:
    - Request
    - RequestMethod
    - Response

  - name: Response Pipeline
    children:
    - Pipeline
    - PipelineStage
    - PipelineStageKey
    - ResponseTransformer
    - ResponseContentTransformer
    - JSONResponseTransformer(_:)
    - TextResponseTransformer(_:)
    - ImageResponseTransformer(_:)

  - name: UI Helpers
    children:
    - ResourceStatusOverlay
    - RemoteImageView

  - name: Network Layer
    children:
    - NetworkingProvider
    - NetworkingProviderConvertible
    - RequestNetworking
    - RequestNetworkingCompletionCallback
    - RequestTransferMetrics
    - NSURLSessionProvider
    - AlamofireProvider

  - name: Caching
    children:
    - EntityCache
    - EntityCacheKey
    - EntityEncoder
    - JSONEntityEncoder

  - name: Logging
    children:
    - enabledLogCategories
    - LogCategory
    - logger

# Until Cocoadocs is using a Jazzy release with the updated config keys:

module_name: Siesta
author_name: Bust Out Solutions
excluded_files: [Source/Support/Siesta-ObjC.swift, Source/Support/Deprecations.swift]