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

わいわいDocC ~ waiwai-docc ~

011714704c4a925e542d426d4cdaa4e3?s=47 giginet
November 16, 2021

わいわいDocC ~ waiwai-docc ~

011714704c4a925e542d426d4cdaa4e3?s=128

giginet

November 16, 2021
Tweet

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

  5. Sloth Creator • SlothCreator: Building DocC Documentation in Xcode |

    Apple Developer Documentation • Appleͷαϯϓϧίʔυɻ͍Ζ͍Ζ࣮ݧ͢Δͷʹ࢖͑Δɻ 5
  6. 6

  7. 7

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

  22. Documentation Archive • *.docarchive ͱ͍͏σΟϨΫτϦ • Documentation BundleΛϏϧυͯ͠render͕ಡΊΔܗࣜʹίϯ ύΠϧͨ͠΋ͷ •

    *.md΍*.tutorial͕શ෦JSONʹίϯύΠϧ͞Εͯ٧Ίࠐ·Εͯ ͍Δ 22
  23. 23

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

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

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

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

  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