Share
Embed
Transcript
52 slides
-
docc? • Documentation Compiler • Xcode 13͔Β౷߹͞ΕͨυΩϡϝϯςʔγϣϯڥ • ιʔείʔυதͷDocumentation Comment͔ΒmarkdownΛग़
ྗΛͨ͠ΓɺνϡʔτϦΞϧจষΛ࡞ͨ͠Γ͕Ͱ͖Δ 2 -
/// A model representing a sloth. /// /// Sloths are
mammals known for their slowness of movement. They spend most of their /// lives hanging upside down in trees. /// /// You can create a sloth using the ``init(name:color:power:)`` initializer, or /// create a randomly generated sloth using a ``SlothGenerator``: /// /// ```swift /// let slothGenerator = MySlothGenerator(seed: randomSeed()) /// let habitat = Habitat(isHumid: false, isWarm: true) /// do { /// let sloth = try slothGenerator.generateSloth(in: habitat) /// } catch { /// fatalError(String(describing: error)) /// } /// ``` public struct Sloth { /// The name of the sloth. public var name: String 3 -
Sloth Creator • SlothCreator: Building DocC Documentation in Xcode |
Apple Developer Documentation • Appleͷαϯϓϧίʔυɻ͍Ζ͍Ζ࣮ݧ͢Δͷʹ͑Δɻ 5 -
ొਓ • Documentation Bundle(*.docc) • υΩϡϝϯτͷݩσʔλ • Symbol Graph(*.symbols.json) •
ࣗಈੜ͞ΕͨίʔυγϯϘϧͷҰཡ • Documentation Archive(.doccarchive) • render͕ಡΈࠐΊΔίϯύΠϧࡁΈσʔλ 14 -
Documentation Bundle(Catalog) • ίϯύΠϧલͷDocumentation • ҎԼΛ٧Ίͨ*.doccͱ͍͏σΟϨΫτϦ • Article(*.md) • Tutorial(*.tutorial)
• symbol-graph(*.symbols.json) 16 -
Symbol Graph • ύοέʔδதͷSymbolΛද͢தؒදݱ • *.symbols.json • ௨ৗɺswiftc͕Ϗϧυͷ͍ͭͰʹੜ • Documentation
Commentͷύʔε͜ͷஈ֊ͰߦΘΕΔ • ͔͜͜ΒReferenceΛੜ 18 -
{ "metadata": { "formatVersion": { "major": 0, "minor": 5, "patch":
3 }, "generator": "Apple Swift version 5.5.2 (swiftlang-1300.0.40.106 clang-1300.0.29.21)" }, "module": { "name": "WaiwaiKit", "platform": { "architecture": "arm64", "vendor": "apple", "operatingSystem": { "name": "macosx", "minimumVersion": { "major": 10, "minor": 10, "patch": 0 } } } }, 19 -
"symbols": [ { "kind": { "identifier": "swift.struct", "displayName": "Structure" },
"identifier": { "precise": "s:9WaiwaiKit5EventV", "interfaceLanguage": "swift" }, "pathComponents": [ "Event" ], "names": { "title": "Event", "navigator": [ { "kind": "identifier", "spelling": "Event" } ], "subHeading": [ { "kind": "keyword", "spelling": "struct" }, { "kind": "text", "spelling": " " }, { "kind": "identifier", "spelling": "Event" } ] }, 20 -
Documentation Archive • *.docarchive ͱ͍͏σΟϨΫτϦ • Documentation BundleΛϏϧυͯ͠render͕ಡΊΔܗࣜʹίϯ ύΠϧͨ͠ͷ •
*.md*.tutorial͕શ෦JSONʹίϯύΠϧ͞Εͯ٧Ίࠐ·Εͯ ͍Δ 22 -
WaiwaiKitͷυΩϡϝϯτΛϒϥβͰදࣔ $ export DOCC_HTML_DIR="$(dirname $(xcrun --find docc))/../share/docc/render" $ make preview
• docc ͕WebαʔόʔΛ্ཱͪ͛ͯΩϞ͍ • hot reload·Ͱ͍ͯΔ 28 -
༨ஊ • doccͷCLIΛ͏ͨΊʹɺPackage.swift ʹswift-doccΛؚΊΕ Α͍ͷͰʁ • → ݱঢ়ɺଞύοέʔδ͔Βґଘʹͨ͠ͱ͖ʹ্ख͘ґଘ͕ؔ resolveͰ͖ͳͯ͘յΕ͍ͯͨͷͰߩݙνϟϯε͔ •
Package.swift ʹมͳϋοΫ͕ͯ͋ͬͯ͠CIΛ௨ա͍ͯͯ͠ݫ ͍͠ 30 -
Symbol GraphͷϏϧυ • swiftc͕ΔͷͰɺ-emit-symbol-graph Λͯ͋͛͠Δ $ swift build --target WaiwaiKit
\ -Xswiftc -emit-symbol-graph \ -Xswiftc -emit-symbol-graph-dir -Xswiftc .build/symbol-graphs 31 -
doccarchiveͷϏϧυ • CSSJSͳͲΛؚΉͷͰɺDOCC_HTML_DIRͷࢦఆ͕ඞཁ $ export DOCC_HTML_DIR="$(dirname $(xcrun --find docc))/../share/docc/render" $
swift run docc convert Sources/WaiwaiKit --output-path WaiwaiKit.doccarchive 32 -
• *.docc/Info.plist ͕ͳ͍߹͜͜ͰfallbackΛࢦఆ͢Δඞཁ ͕͋Δ $ swift run docc convert Sources/WaiwaKit/WaiwaiKit.docc
\ --fallback-display-name WaiwaiKit \ --fallback-bundle-identifier me.giginet.WaiwaiKit \ --fallback-bundle-version 1.0.0 \ --additional-symbol-graph-dir .build/symbol-graphs 33 -
Xcodeଐͷdoccbuild $ xcodebuild doccbuild -scheme WaiwaiKit -project WaiwaiKit.xcodeproj -destination ...
• -emit-symbol-graph ͱ docc convert ʹ૬͢Δ͜ͱΛΔͬ Ά͍ 34 -
Documentation Commentͷύʔε /// աڈʹ։࠵ͨ͠ΠϕϯτΛද͢Ϟσϧ /// ```swift /// let event =
Event( /// ... /// ) /// ``` public struct Event { ///ɹ։࠵൪߸ public var number: Int // ... } 35 -
"docComment": { "lines": [ { "range": { "start": { "line":
2, "character": 4 }, "end": { "line": 2, "character": 55 } }, "text": "աڈʹ։࠵ͨ͠ΠϕϯτΛද͢Ϟσϧ" }, { "range": { "start": { "line": 3, "character": 4 }, "end": { "line": 3, "character": 12 } }, "text": "```swift" }, { "range": { "start": { "line": 4, "character": 4 }, "end": { "line": 4, "character": 22 } }, "text": "let event = Event(" }, 36 -
WaiwaiKit.doccarchive/data/documentation/WaiwaiKit/ event.json { "primaryContentSections": [ { "kind": "declarations", "declarations": [
{ "tokens": [ { "kind": "keyword", "text": "struct" }, { "kind": "text", "text": " " }, { "kind": "identifier", "text": "Event" } ], "languages": [ "swift" ], "platforms": [ "macOS" ] } ] }, 38 -
{ "kind": "content", "content": [ { "anchor": "overview", "level": 2,
"type": "heading", "text": "Overview" }, { "type": "codeListing", "syntax": "swift", "code": [ "let event = Event(", " ...", ")" ] } ] } ], 39 -
@Tutorials(name: "WaiwaiKit") { @Intro(title: "Meet WaiwaiKit") { Learn how to
work swift-docc @Image(source: "logo.png", alt: "So cool logo!") } @Chapter(name: "WaiwaiKit Essentials") { WaiwaiKitͷجຊతͳ͍ํΛֶͼ·͠ΐ͏ @TutorialReference(tutorial: "doc:Using-WaiwaiKit") } } waiwai-docc/WaiwaiKit.tutorial at main · waiwai-swiftc/waiwai- docc 43 -
@Tutorial(time: 1) { @Intro(title: "Using WaiwaiKit") { WaiwaiKitΛͬͯΈ·͠ΐ͏ @Image(source: "logo.png",
alt: "cool logo") } @Section(title: "Tutorial") { @ContentAndMedia { WaiwaiKitΛͬͯաڈͷΠϕϯτΛऔಘ͢Δ } @Steps { @Step { Hi! I'm giginet! ͜Μʹͪ @Image(source: "giginet.png", alt: "cute cat!") } @Comment { ίϝϯτ } @Step { ΠϕϯτΛऔಘͯ͠Έ·͠ΐ͏ @Code(name: "GetPreviousEvent.swift", file: tutorial0.swift) { } } @Step { Ͱ͖ͨ } } } } 45 -
• SyntaxṖ • doccͷυΩϡϝϯτɺWWDCͷಈըͰޠΒΕ͍ͯΔɻ • swift-docc/Directives.md at d94139a5e64e9ecf158214b1cded2a2880fc1b02 · apple/
swift-docc • ͜ΕdoccarchiveʹϏϧυͨ͠ͱ͖ʹṖͷJSONʹͳΔ • ͱ͜ΖͲ͜ΖຊޠؚΉͱϏϧυࣦഊ͔ͨ͠Βߩݙνϟϯε 47 -
• ͦͷଞɺಠࣗͷSyntax͕ଟ͔ͯ͘ͳΓෳࡶ • DirectiveʹΑΔϦϑΝϨϯεͷࡉ͔ͳ੍ޚ • τοϓϖʔδͷOverviewΛ࿔ΕΔTechnologyRootͳͲ • doccͷdocʹॻ͔Ε͍ͯΔ • swift-docc/Sources/DocCDocumentation/
DocCDocumentation.docc at main · apple/swift-docc 48