わいわいDocC ~ waiwai-docc ~

Transcript

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

   View Slide

2. docc?
   • Documentation Compiler
   • Xcode 13͔Β౷߹͞ΕͨυΩϡϝϯςʔγϣϯ؀ڥ
   • ιʔείʔυதͷDocumentation Comment͔ΒmarkdownΛग़
   ྗΛͨ͠ΓɺνϡʔτϦΞϧจষΛ࡞੒ͨ͠Γ͕Ͱ͖Δ
   2
   

   View Slide

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
   

   View Slide

4. View Slide

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

   View Slide

6. View Slide

7. View Slide

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

   View Slide

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

   View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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
    

    View Slide

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

    View Slide

15. Pipeline
    15
    

    View Slide

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

    View Slide

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

    View Slide

18. Symbol Graph
    • ύοέʔδதͷSymbolΛද͢தؒදݱ
    • *.symbols.json
    • ௨ৗɺswiftc͕Ϗϧυͷ͍ͭͰʹੜ੒
    • Documentation Commentͷύʔε΋͜ͷஈ֊ͰߦΘΕΔ
    • ͔͜͜ΒReferenceΛੜ੒
    18
    

    View Slide

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
    

    View Slide

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
    

    View Slide

21. View Slide

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

    View Slide

23. View Slide

24. Pipeline
    24
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

29. View Slide

30. ༨ஊ
    • doccͷCLIΛ࢖͏ͨΊʹɺPackage.swift ʹswift-doccΛؚΊΕ
    ͹Α͍ͷͰ͸ʁ
    • → ݱঢ়ɺଞύοέʔδ͔Βґଘʹͨ͠ͱ͖ʹ্ख͘ґଘؔ܎͕
    resolveͰ͖ͳͯ͘յΕ͍ͯͨͷͰߩݙνϟϯε͔΋
    • Package.swift ʹมͳϋοΫ͕ͯ͋ͬͯ͠CIΛ௨ա͍ͯͯ͠ݫ
    ͍͠
    30
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

34. Xcode෇ଐͷdoccbuild
    $ xcodebuild doccbuild -scheme WaiwaiKit -project WaiwaiKit.xcodeproj -destination ...
    • -emit-symbol-graph ͱ docc convert ʹ૬౰͢Δ͜ͱΛ΍Δͬ
    Ά͍
    34
    

    View Slide

35. Documentation Commentͷύʔε
    /// աڈʹ։࠵ͨ͠ΠϕϯτΛද͢Ϟσϧ
    /// ```swift
    /// let event = Event(
    /// ...
    /// )
    /// ```
    public struct Event {
    ///ɹ։࠵൪߸
    public var number: Int
    // ...
    }
    35
    

    View Slide

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
    

    View Slide

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

    View Slide

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
    

    View Slide

39. {
    "kind": "content",
    "content": [
    {
    "anchor": "overview",
    "level": 2,
    "type": "heading",
    "text": "Overview"
    },
    {
    "type": "codeListing",
    "syntax": "swift",
    "code": [
    "let event = Event(",
    " ...",
    ")"
    ]
    }
    ]
    }
    ],
    39
    

    View Slide

40. View Slide

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

    View Slide

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

    View Slide

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
    

    View Slide

44. View Slide

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
    

    View Slide

46. View Slide

47. • Syntax͸Ṗ
    • doccͷυΩϡϝϯτ΍ɺWWDCͷಈըͰޠΒΕ͍ͯΔɻ
    • swift-docc/Directives.md at
    d94139a5e64e9ecf158214b1cded2a2880fc1b02 · apple/
    swift-docc
    • ͜Ε΋doccarchiveʹϏϧυͨ͠ͱ͖ʹṖͷJSONʹͳΔ
    • ͱ͜ΖͲ͜Ζ೔ຊޠؚΉͱϏϧυࣦഊ͔ͨ͠Βߩݙνϟϯε
    47
    

    View Slide

48. • ͦͷଞɺಠࣗͷSyntax͕ଟ͔ͯ͘ͳΓෳࡶ
    • DirectiveʹΑΔϦϑΝϨϯεͷࡉ͔ͳ੍ޚ
    • τοϓϖʔδͷOverviewΛ࿔ΕΔTechnologyRootͳͲ
    • doccͷdocʹॻ͔Ε͍ͯΔ
    • swift-docc/Sources/DocCDocumentation/
    DocCDocumentation.docc at main · apple/swift-docc
    48
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide