Θ͍Θ͍docc Θ͍Θ͍swiftc #31 2021/11/16 @giginet 1

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

4

Sloth Creator • SlothCreator: Building DocC Documentation in Xcode | Apple Developer Documentation • Appleͷαϯϓϧίʔυɻ͍Ζ͍Ζ࣮ݧ͢Δͷʹ࢖͑Δɻ 5

6

7

• swift-docc • symbol-kit • swift-markdown • Swift-DocC-Render • Swift-DocC-Render-artifact 8

swift-docc https://github.com/apple/swift-docc • DocumentationίϯύΠϥຊମͱCLI • DSLͷύʔε΍ɺdoccͷίϯύΠϧɺϓϨϏϡʔͷͨΊͷαʔ όʔىಈͳͲ͍Ζ͍Ζ΍ͬͯ͘ΕΔ • σΧ͍ 9

SymbolKit https://github.com/apple/swift-docc-symbolkit • module಺ͷsymbol(class, struct, protocol...)ΛϞσϧԽ͢ΔͨΊ ͷϑϨʔϜϫʔΫ • σΧ͍Codable 10

SwiftMarkdown https://github.com/apple/swift-markdown • Swift੡ͷMarkdownϨϯμϥʔɺύʔαʔ • MarkdownΛ಺෦දݱʹม׵ͨ͠Γɺٯʹϊʔυ͔ΒMarkdown Λੜ੒Ͱ͖Δ • ଞͷ༻్ʹ΋͍Ζ͍Ζ࢖͑ͦ͏ 11

Swift-DocC-Render https://github.com/apple/swift-docc-render • DocCΛϨϯμϦϯά͢ΔͨΊͷWeb-front • VueJS੡ͷWebΞϓϦέʔγϣϯ • SPA(Single Page Application)ʹͳ͍ͬͯΔɻυΩϡϝϯτίϯ ςϯπΛಡΈࠐΜͰϖʔδΛੜ੒͢Δ • σΧ͍ 12

swift-docc-render-artifact https://github.com/apple/swift-docc-render-artifact • ϏϧυࡁΈͷRendererҰࣜ • Xcodeʹ෇ଐͯ͠Δ෺ͱಉ͡ • Xcode.app/Contents/Developer/Toolchains/ XcodeDefault.xctoolchain/usr/share/docc/render ʹ͍Δ 13

ొ৔ਓ෺ • Documentation Bundle(*.docc) • υΩϡϝϯτͷݩσʔλ • Symbol Graph(*.symbols.json) • ࣗಈੜ੒͞ΕͨίʔυγϯϘϧͷҰཡ • Documentation Archive(.doccarchive) • render͕௚઀ಡΈࠐΊΔίϯύΠϧࡁΈσʔλ 14

Pipeline 15

Documentation Bundle(Catalog) • ίϯύΠϧલͷDocumentation • ҎԼΛ٧Ίͨ*.doccͱ͍͏σΟϨΫτϦ • Article(*.md) • Tutorial(*.tutorial) • symbol-graph(*.symbols.json) 16

• ҎԼΛ٧Ίͨ*.doccͱ͍͏σΟϨΫτϦ • Info.plist • Assetʢը૾ɺಈըɺιʔείʔυͳͲʣ • https://github.com/apple/swift-docc/blob/ d94139a5e64e9ecf158214b1cded2a2880fc1b02/Sources/ SwiftDocC/SwiftDocC.docc/SwiftDocC/CompilerPipeline.md 17

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

21

Documentation Archive • *.docarchive ͱ͍͏σΟϨΫτϦ • Documentation BundleΛϏϧυͯ͠render͕ಡΊΔܗࣜʹίϯ ύΠϧͨ͠΋ͷ • *.md΍*.tutorial͕શ෦JSONʹίϯύΠϧ͞Εͯ٧Ίࠐ·Εͯ ͍Δ 22

23

Pipeline 24

Sample Project ؀ڥΛ࡞Δͷ͕େมͳͷͰ༡΂Δ΍ͭ https://github.com/waiwai-swiftc/waiwai-docc 25

• SwiftPMͷґଘͱͯ͠executableΛ΋Βͬͯ͠·͏ͷ͕ૣ͍ • Θ͕͠ࠓே௚ͨ͠ ! dependencies: [ .package(url: "https://github.com/apple/swift-docc.git", .branch("main")), ], 26

doccͷϏϧυ $ git clone https://github.com/apple/swift-docc $ cd swift-docc $ swift build 27

WaiwaiKitͷυΩϡϝϯτΛϒϥ΢βͰදࣔ $ export DOCC_HTML_DIR="$(dirname $(xcrun --find docc))/../share/docc/render" $ make preview • docc ͕WebαʔόʔΛ্ཱͪ͛ͯΩϞ͍ • hot reload·Ͱ෇͍ͯΔ 28

29

༨ஊ • 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ͷϏϧυ • CSS΍JSͳͲΛؚΉͷͰɺ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

• Symbol Graphͷஈ֊Ͱ͸1ߦͣͭline, column, textΛ͚࣋ͭͩ 37

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

40

• doccarchiveʹϏϧυ͞ΕΔ͜ͱͰɺߏ଄Խ͞ΕΔ 41

Tutorial • *.tutorialͱ͍͏ṖͷDSLʹΑͬͯॻ͔ΕΔνϡʔτϦΞϧυ Ωϡϝϯτ 42

@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

44

@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

46

• 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

·ͱΊ • ͍ٕ͢͝ज़͸ͦΜͳʹͳͯ͘ɺΰϦΰϦʹ࣮૷͞Ε͍ͯΔ • Webϑϩϯτ΋͔ͳΓϦονͳͷͰɺWebΞϓϦέʔγϣϯͷ ࣗ࡞͸ࠎ͕ંΕͦ͏ • symbol-graphΛύʔε͢Δ͜ͱͰɺΫϥεਤΈ͍ͨͳͷ͸ࣗಈ ੜ੒Ͱ͖Δ͔΋ʁ 49

͜Ε͔ΒͷOSSʢײ૝ʣ • ͱΓ͋͑ͣSources/MyPackage/MyPackage.doccΛஔ͍͓ͯ͘ͱ Αͦ͞͏ • Xcode෇ଐͷOrganizerͰϩʔΧϧͰݟΕΔΑ͏ʹͳΔ • DockerͰͲʔΜͱ΍ͬͯ؆୯ʹσϓϩΠͰ͖Δج൫͕ཉ͍͠ • ͜͜·ͰἧͬͯΕ͹͙͢ʹ࡞Εͦ͏ 50

ൃల՝୊ ͕࣌ؒͳ͔ͬͨͷͰௐ΂ͭͭΘ͍Θ͍͠·͠ΐ͏ • *.doccarchive/data ΛݟͯΈΑ͏ • -emit-symbol-graphsͷಈ࡞ΛݟͯΈΑ͏ • TutorialͷύʔαʔΛݟͯΈΑ͏ • rendererͷ࣮૷ΛݟͯΈΑ͏ 51

• swift/lib/SymbolGraphGen at bd07973e1db86bf46600a2af507aea0f52d177d3 · apple/swift 52