Upgrade to Pro — share decks privately, control downloads, hide ads and more …

わいわいDocC ~ waiwai-docc ~

giginet
PRO
November 16, 2021

わいわいDocC ~ waiwai-docc ~

giginet
PRO

November 16, 2021
Tweet

More Decks by giginet

Other Decks in Technology

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. 4

    View Slide

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

    View Slide

  6. 6

    View Slide

  7. 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. 21

    View Slide

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

    View Slide

  23. 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. 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. 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. 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. 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