Jazzy 사용법

기타 2016. 10. 28. 09:13
반응형

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과 privatepublic 항목도 처리 가능하다.

원하는 클래스만 문서화되길 원한다면 직접 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]


반응형
Posted by 까칠코더
,