わいわいDocC ~ waiwai-docc ~

Transcript

1. Θ͍Θ͍docc Θ͍Θ͍swiftc #31 2021/11/16 @giginet 1
2. docc? • Documentation Compiler • Xcode 13͔Β౷߹͞ΕͨυΩϡϝϯςʔγϣϯ؀ڥ • ιʔείʔυதͷDocumentation Comment͔ΒmarkdownΛग़ ྗΛͨ͠ΓɺνϡʔτϦΞϧจষΛ࡞੒ͨ͠Γ͕Ͱ͖Δ 2
3. /// 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
5. Sloth Creator • SlothCreator: Building DocC Documentation in Xcode | Apple Developer Documentation • Appleͷαϯϓϧίʔυɻ͍Ζ͍Ζ࣮ݧ͢Δͷʹ࢖͑Δɻ 5
8. • swift-docc • symbol-kit • swift-markdown • Swift-DocC-Render • Swift-DocC-Render-artifact 8
9. swift-docc https://github.com/apple/swift-docc • DocumentationίϯύΠϥຊମͱCLI • DSLͷύʔε΍ɺdoccͷίϯύΠϧɺϓϨϏϡʔͷͨΊͷαʔ όʔىಈͳͲ͍Ζ͍Ζ΍ͬͯ͘ΕΔ • σΧ͍ 9
10. SymbolKit https://github.com/apple/swift-docc-symbolkit • module಺ͷsymbol(class, struct, protocol...)ΛϞσϧԽ͢ΔͨΊ ͷϑϨʔϜϫʔΫ • σΧ͍Codable 10
11. SwiftMarkdown https://github.com/apple/swift-markdown • Swift੡ͷMarkdownϨϯμϥʔɺύʔαʔ • MarkdownΛ಺෦දݱʹม׵ͨ͠Γɺٯʹϊʔυ͔ΒMarkdown Λੜ੒Ͱ͖Δ • ଞͷ༻్ʹ΋͍Ζ͍Ζ࢖͑ͦ͏ 11
12. Swift-DocC-Render https://github.com/apple/swift-docc-render • DocCΛϨϯμϦϯά͢ΔͨΊͷWeb-front • VueJS੡ͷWebΞϓϦέʔγϣϯ • SPA(Single Page Application)ʹͳ͍ͬͯΔɻυΩϡϝϯτίϯ ςϯπΛಡΈࠐΜͰϖʔδΛੜ੒͢Δ • σΧ͍ 12
13. 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
14. ొ৔ਓ෺ • Documentation Bundle(*.docc) • υΩϡϝϯτͷݩσʔλ • Symbol Graph(*.symbols.json) • ࣗಈੜ੒͞ΕͨίʔυγϯϘϧͷҰཡ • Documentation Archive(.doccarchive) • render͕௚઀ಡΈࠐΊΔίϯύΠϧࡁΈσʔλ 14
15. Pipeline 15
16. Documentation Bundle(Catalog) • ίϯύΠϧલͷDocumentation • ҎԼΛ٧Ίͨ*.doccͱ͍͏σΟϨΫτϦ • Article(*.md) • Tutorial(*.tutorial) • symbol-graph(*.symbols.json) 16
17. • ҎԼΛ٧Ίͨ*.doccͱ͍͏σΟϨΫτϦ • Info.plist • Assetʢը૾ɺಈըɺιʔείʔυͳͲʣ • https://github.com/apple/swift-docc/blob/ d94139a5e64e9ecf158214b1cded2a2880fc1b02/Sources/ SwiftDocC/SwiftDocC.docc/SwiftDocC/CompilerPipeline.md 17
18. Symbol Graph • ύοέʔδதͷSymbolΛද͢தؒදݱ • *.symbols.json • ௨ৗɺswiftc͕Ϗϧυͷ͍ͭͰʹੜ੒ • Documentation Commentͷύʔε΋͜ͷஈ֊ͰߦΘΕΔ • ͔͜͜ΒReferenceΛੜ੒ 18
19. { "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
20. "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
22. Documentation Archive • *.docarchive ͱ͍͏σΟϨΫτϦ • Documentation BundleΛϏϧυͯ͠render͕ಡΊΔܗࣜʹίϯ ύΠϧͨ͠΋ͷ • *.md΍*.tutorial͕શ෦JSONʹίϯύΠϧ͞Εͯ٧Ίࠐ·Εͯ ͍Δ 22
24. Pipeline 24
25. Sample Project ؀ڥΛ࡞Δͷ͕େมͳͷͰ༡΂Δ΍ͭ https://github.com/waiwai-swiftc/waiwai-docc 25
26. • SwiftPMͷґଘͱͯ͠executableΛ΋Βͬͯ͠·͏ͷ͕ૣ͍ • Θ͕͠ࠓே௚ͨ͠ ! dependencies: [ .package(url: "https://github.com/apple/swift-docc.git", .branch("main")), ], 26
27. doccͷϏϧυ $ git clone https://github.com/apple/swift-docc $ cd swift-docc $ swift build 27
28. WaiwaiKitͷυΩϡϝϯτΛϒϥ΢βͰදࣔ $ export DOCC_HTML_DIR="$(dirname $(xcrun --find docc))/../share/docc/render" $ make preview • docc ͕WebαʔόʔΛ্ཱͪ͛ͯΩϞ͍ • hot reload·Ͱ෇͍ͯΔ 28
30. ༨ஊ • doccͷCLIΛ࢖͏ͨΊʹɺPackage.swift ʹswift-doccΛؚΊΕ ͹Α͍ͷͰ͸ʁ • → ݱঢ়ɺଞύοέʔδ͔Βґଘʹͨ͠ͱ͖ʹ্ख͘ґଘؔ܎͕ resolveͰ͖ͳͯ͘յΕ͍ͯͨͷͰߩݙνϟϯε͔΋ • Package.swift ʹมͳϋοΫ͕ͯ͋ͬͯ͠CIΛ௨ա͍ͯͯ͠ݫ ͍͠ 30
31. Symbol GraphͷϏϧυ • swiftc͕΍ΔͷͰɺ-emit-symbol-graph Λ౉ͯ͋͛͠Δ $ swift build --target WaiwaiKit \ -Xswiftc -emit-symbol-graph \ -Xswiftc -emit-symbol-graph-dir -Xswiftc .build/symbol-graphs 31
32. 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
33. • *.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
34. Xcode෇ଐͷdoccbuild $ xcodebuild doccbuild -scheme WaiwaiKit -project WaiwaiKit.xcodeproj -destination ... • -emit-symbol-graph ͱ docc convert ʹ૬౰͢Δ͜ͱΛ΍Δͬ Ά͍ 34
35. Documentation Commentͷύʔε /// աڈʹ։࠵ͨ͠ΠϕϯτΛද͢Ϟσϧ /// ```swift /// let event = Event( /// ... /// ) /// ``` public struct Event { ///ɹ։࠵൪߸ public var number: Int // ... } 35
36. "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
37. • Symbol Graphͷஈ֊Ͱ͸1ߦͣͭline, column, textΛ͚࣋ͭͩ 37
38. 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
39. { "kind": "content", "content": [ { "anchor": "overview", "level": 2, "type": "heading", "text": "Overview" }, { "type": "codeListing", "syntax": "swift", "code": [ "let event = Event(", " ...", ")" ] } ] } ], 39
41. • doccarchiveʹϏϧυ͞ΕΔ͜ͱͰɺߏ଄Խ͞ΕΔ 41
42. Tutorial • *.tutorialͱ͍͏ṖͷDSLʹΑͬͯॻ͔ΕΔνϡʔτϦΞϧυ Ωϡϝϯτ 42
43. @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
45. @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
47. • Syntax͸Ṗ • doccͷυΩϡϝϯτ΍ɺWWDCͷಈըͰޠΒΕ͍ͯΔɻ • swift-docc/Directives.md at d94139a5e64e9ecf158214b1cded2a2880fc1b02 · apple/ swift-docc • ͜Ε΋doccarchiveʹϏϧυͨ͠ͱ͖ʹṖͷJSONʹͳΔ • ͱ͜ΖͲ͜Ζ೔ຊޠؚΉͱϏϧυࣦഊ͔ͨ͠Βߩݙνϟϯε 47
48. • ͦͷଞɺಠࣗͷSyntax͕ଟ͔ͯ͘ͳΓෳࡶ • DirectiveʹΑΔϦϑΝϨϯεͷࡉ͔ͳ੍ޚ • τοϓϖʔδͷOverviewΛ࿔ΕΔTechnologyRootͳͲ • doccͷdocʹॻ͔Ε͍ͯΔ • swift-docc/Sources/DocCDocumentation/ DocCDocumentation.docc at main · apple/swift-docc 48
49. ·ͱΊ • ͍ٕ͢͝ज़͸ͦΜͳʹͳͯ͘ɺΰϦΰϦʹ࣮૷͞Ε͍ͯΔ • Webϑϩϯτ΋͔ͳΓϦονͳͷͰɺWebΞϓϦέʔγϣϯͷ ࣗ࡞͸ࠎ͕ંΕͦ͏ • symbol-graphΛύʔε͢Δ͜ͱͰɺΫϥεਤΈ͍ͨͳͷ͸ࣗಈ ੜ੒Ͱ͖Δ͔΋ʁ 49
50. ͜Ε͔ΒͷOSSʢײ૝ʣ • ͱΓ͋͑ͣSources/MyPackage/MyPackage.doccΛஔ͍͓ͯ͘ͱ Αͦ͞͏ • Xcode෇ଐͷOrganizerͰϩʔΧϧͰݟΕΔΑ͏ʹͳΔ • DockerͰͲʔΜͱ΍ͬͯ؆୯ʹσϓϩΠͰ͖Δج൫͕ཉ͍͠ • ͜͜·ͰἧͬͯΕ͹͙͢ʹ࡞Εͦ͏ 50
51. ൃల՝୊ ͕࣌ؒͳ͔ͬͨͷͰௐ΂ͭͭΘ͍Θ͍͠·͠ΐ͏ • *.doccarchive/data ΛݟͯΈΑ͏ • -emit-symbol-graphsͷಈ࡞ΛݟͯΈΑ͏ • TutorialͷύʔαʔΛݟͯΈΑ͏ • rendererͷ࣮૷ΛݟͯΈΑ͏ 51
52. • swift/lib/SymbolGraphGen at bd07973e1db86bf46600a2af507aea0f52d177d3 · apple/swift 52