$30 off During Our Annual Pro Sale. View Details »

DocC Documentation Archiveをアプリ開発で活用してみよう / DocC Documentation Archive for iOS Application

aoi
September 28, 2022

DocC Documentation Archiveをアプリ開発で活用してみよう / DocC Documentation Archive for iOS Application

aoi

September 28, 2022
Tweet

More Decks by aoi

Other Decks in Technology

Transcript

  1. DocC Documentation Archive Λ ΞϓϦ։ൃͰ׆༻ͯ͠ΈΑ͏ 2022/09/28 After Party iOSDC Japan

    2022 @aomathwift
  2. ࣗݾ঺հ Aoi Okawa (@aomathwift) Cookpad Inc. iOS Developer Cookpad Mart

  3. ͓͜ͱΘΓ • ͜Ε͸ΞϓϦͷυΩϡϝϯτΛ DocC ʹஔ͖׵͑ͨͱ͍͏ࣄྫͷ࿩Ͱ ͸͋Γ·ͤΜ • ΞϓϦέʔγϣϯλʔήοτͰ DocC Λॱ౰ʹѻ͏ํ๏ʹ͍ͭͯ͸ৄ

    ͘͠৮Ε·ͤΜ • ͋͘·ͰݕূͱΞΠσΞͷ࿩ͱͯ͠ฉ͍͍ͯͩ͘͞
  4. Swift-DocC ͰͷυΩϡϝϯτ࡞੒

  5. Swift-DocC ͱ͸ • Apple ७ਖ਼ͷυΩϡϝϯτ࡞੒πʔϧ • Xcode 13 Ҏ߱ʹ౷߹ •

    OSS ͱͯ͠΋ެ։͞Ε͍ͯΔ
  6. None
  7. Swift-DocC ͷΞοϓσʔτ • Xcode 13.3 ͔ΒΞϓϦέʔγϣϯ޲͚ͷϏϧυΛαϙʔτ • Github Pages ʹ؆୯ʹϗεςΟϯάͰ͖Δػೳ

    → ΞϓϦυΩϡϝϯτͷ DocC ԽΛקΊΔػӡʁ
  8. ΞϓϦʹඞཁͳυΩϡϝϯτ • ϓϩδΣΫτͷߏ੒΍ΞʔΩςΫνϟ • CI / CD ʹ͍ͭͯ • ։ൃϑϩʔ΍։ൃ؀ڥͷηοτΞοϓ

    • Utility Ϋϥεͷϝιου΍ϓϩύςΟͷઆ໌
  9. ΞϓϦʹඞཁͳυΩϡϝϯτ • ϓϩδΣΫτͷߏ੒΍ΞʔΩςΫνϟ • CI / CD ʹ͍ͭͯ • ։ൃϑϩʔ΍։ൃ؀ڥͷηοτΞοϓ

    • Utility Ϋϥεͷϝιου΍ϓϩύςΟͷઆ໌ → Documentation Έ͍ͨͳσΟϨΫτϦ഑Լʹஔ͍͍ͯΔ
  10. ΞϓϦʹඞཁͳυΩϡϝϯτ • ϓϩδΣΫτͷߏ੒΍ΞʔΩςΫνϟ • CI / CD ʹ͍ͭͯ • ։ൃϑϩʔ΍։ൃ؀ڥͷηοτΞοϓ

    • Utility Ϋϥεͷϝιου΍ϓϩύςΟͷઆ໌ → README.md ΍ CONTRIBUTING.md
  11. None
  12. ΞϓϦʹඞཁͳυΩϡϝϯτ • ϓϩδΣΫτͷߏ੒΍ΞʔΩςΫνϟ • CI / CD ʹ͍ͭͯ • ։ൃϑϩʔ΍։ൃ؀ڥͷηοτΞοϓ

    • Utility Ϋϥεͷϝιου΍ϓϩύςΟͷઆ໌ → ίʔυίϝϯτ = DocC ͷه๏Λར༻
  13. ΞϓϦʹඞཁͳυΩϡϝϯτ • ϓϩδΣΫτͷߏ੒΍ΞʔΩςΫνϟ • CI / CD ʹ͍ͭͯ • ։ൃϑϩʔ΍։ൃ؀ڥͷηοτΞοϓ

    • Utility Ϋϥεͷϝιου΍ϓϩύςΟͷઆ໌ → Documentation Catalog Λ࢖͏
  14. Documentation Catalog •Markdownهࣄ΍֦ுϑΝΠϧΛ ؚΊΔ͜ͱͰಛఆͷAPIͷઆ໌Ҏ֎ ͷ෦෼ͷυΩϡϝϯτΛิ׬ •ެࣜυΩϡϝϯτͷ Overview ͷ ϖʔδ౳͕֘౰

  15. ͜͏͢Δͱ DocC ԽͰ͖Δ • طଘͷ Markdown ϑΝΠϧΛ Documentation Catalog ʹೖΕࠐΉ

    • ಛఆͷϝιου΍Ϋϥεͷઆ໌͸ DocC ίϝϯτΛॻ͖ࠐΉ
  16. طଘͷυΩϡϝϯτͰݴ͏ͯࠔͬͯͳ͍ Ͱ΋ DocC ͸ͪΐͬͱ৮ͬͯΈ͍ͨͳ͊🥺

  17. Documentation Archive ͱ͍͏΋ͷΛ༻͍ͯ ผͷܗͰ Swift-DocC Λ׆༻ͯ͠Έ·͠ΐ͏

  18. Agenda • DocC Documentation Archive ͱ͸ • Documentation Archive ͷߏ଄

    • Documentation Archive ͷ׆༻
  19. Documentation Archive ͍ͭͯ

  20. Documentation Archive • *.doccarchive ֦ுࢠΛ࣋ͭυΩϡϝϯτͷຊମσΟϨΫτϦ • Xcode Ͱ։͘ͱ DocC υΩϡϝϯτͱͯ͠ϨϯμϦϯά͞ΕΔ

  21. None
  22. Documentation Archive ͷϏϧυ • Xcode ͷ GUI ͔Β࣮ߦ • Xcode

    ෇ଐͷ doccbuild ίϚϯυͰ࣮ߦ
  23. None
  24. Documentation Archive ͷϏϧυ(CLI) $ xcodebuild -workspace CookpadMart.xcworkspace -scheme "CookpadMart" -sdk

    iphonesimulator -destination 'platform=iOS Simulator,name=iPhone 13 Pro,OS=16.0' docbuild -derivedDataPath .build
  25. Documentation Archive ͷߏ଄

  26. None
  27. *.doccarchive • υΩϡϝϯτΛϨϯμϦϯά͢Δͷʹඞཁͳ৘ใͷू·Γ • Xcode13 ·Ͱ͸͜ͷσΟϨΫτϦΛϏϧυࡁΈυΩϡϝϯτ͔Β௚ ઀ Export Ͱ͖ͨ ※

    Xcode14 ͔Β͸ *.doccarchive/documentation ҎԼͷ HTML ϑΝΠ ϧୡ͔͠ Export Ͱ͖ͳ͍
  28. *.doccarhive/data • ύʔε͞Εͨίϝϯτ౳͕ϝιου΍Ϋϥε͝ͱʹߏ଄Խ͞Εͨ΋ͷ • υΩϡϝϯτͷݟͨ໨Ͳ͓Γͷ৘ใΛ json ͷܗͰ΋ͭ • {Target Name}.json

    ͕ϧʔτʹ͍Δ
  29. { "variants": [ ... ], "schemaVersion": { ... }, "sections":

    [], "identifier": { ... }, "topicSections": [ ... ], "kind": "symbol", "metadata": { ... }, "hierarchy": { ... }, "references": { ... } }
  30. {Target Name}.json • τοϓϖʔδ৘ใʹ͋ͨΔ΋ͷ • topicSections • Classes, Protocols, Structures,

    Variables, … • references • ֤Ϋϥε౳ͷυΩϡϝϯτͷID΍ද໊ࣔ
  31. None
  32. "topicSections": [ { "title": "Classes", "identifiers": [ “doc:\/\/bunle-id\/documentation\/CookpadMartEC\/MartActivityLogger" ... ]

    }, { "title": "Protocols", "identifiers": [ ... ] }, { "title": "Structures", "identifiers": [ ... ] }, { "title": "Variables", "identifiers": [ ... ] }, { "title": "Functions", "identifiers": [ ... }, { "title": "Operators", "identifiers": [ … ] }, { "title": "Type Aliases", "identifiers": [ ... ] }, { "title": "Enumerations", "identifiers": [ ... ] } ] { "variants": [ ... ], "schemaVersion": { ... }, "sections": [], "identifier": { ... }, "topicSections": [ ... ], "kind": "symbol", "metadata": { ... }, "hierarchy": { ... }, "references": { ... } }
  33. "references": { "doc://bundle-id/documentation/CookpadMart/ActivityLogger": { "role": "symbol", "title": "ActivityLogger", "fragments": [

    { "kind": "keyword", "text": "protocol" }, { "kind": "text", "text": " " }, { "kind": "identifier", "text": "ActivityLogger" } ], "identifier": “doc:\/\/bundle-id\/documentation\/ CookpadMart\/ActivityLogger", "kind": "symbol", "type": "topic", "url": “\/documentation\/cookpadmartec\/activitylogger" }, ... } { "variants": [ ... ], "schemaVersion": { ... }, "sections": [], "identifier": { ... }, "topicSections": [ ... ], "kind": "symbol", "metadata": { ... }, "hierarchy": { ... }, "references": { ... } }
  34. ֤ class ͝ͱͷϑΝΠϧɾσΟϨΫτϦ • جຊతʹͦͷϖʔδͷυΩϡϝϯτʹฒ΂ΒΕΔηΫγϣϯͷ৘ใΛ ֤ηΫγϣϯ໊ͷΩʔʹ΋ͨͤΒΕ͍ͯΔ • σΟϨΫτϦҎԼ͸ϝιουɾม਺͝ͱʹಉ༷ͷηΫγϣϯσʔλΛ ΋ͬͨ json

    ϑΝΠϧ͕٧Ίࠐ·Ε͍ͯΔ
  35. { "primaryContentSections": [ ... ], "schemaVersion": { ... }, "sections":

    [], "variants": [ ... ], "relationshipsSections": [ ... ], "identifier": { ... }, "topicSections": [ ... ], "kind": "symbol", "metadata": { ... }, "hierarchy": { ... }, "references": { ... } }
  36. ֤ class ౳ͷϑΝΠϧ • topicSections • Initializers, Instance Properties, Instsnce

    Methods… ͳͲ • primaryContentSections • declaration ͳͲ • relationshipsSections • inheritFrom, conformTo, conformingType
  37. None
  38. "primaryContentSections": [ { "kind": "declarations", "declarations": [ { "tokens": [

    { "kind": "keyword", "text": "protocol" }, { "kind": "text", "text": " " }, { "kind": "identifier", "text": "ActivityLogger" } ], "languages": [ "swift" ], "platforms": [ "iOS" ] } ] } ] { "primaryContentSections": [ ... ], "schemaVersion": { ... }, "sections": [], "variants": [ ... ], "relationshipsSections": [ ... ], "identifier": { ... }, "topicSections": [ ... ], "kind": "symbol", "metadata": { ... }, "hierarchy": { ... }, "references": { ... } }
  39. None
  40. "topicSections": [ { "title": "Structures", "identifiers": [ ... ] },

    { "title": "Initializers", "identifiers": [ ... ] }, { "title": "Instance Properties", "identifiers": [ ... ] }, { "title": "Instance Methods", "identifiers": [ ... ] }, { "title": "Type Aliases", "identifiers": [ ... ] }, { "title": "Type Properties", "identifiers": [ ... ] }, { "title": "Type Methods", "identifiers": [ ... ] }, { "title": "Default Implementations", "identifiers": [ ... ], "generated": true } ] { "primaryContentSections": [ ... ], "schemaVersion": { ... }, "sections": [], "variants": [ ... ], "relationshipsSections": [ ... ], "identifier": { ... }, "topicSections": [ ... ], "kind": "symbol", "metadata": { ... }, "hierarchy": { ... }, "references": { ... } }
  41. None
  42. "relationshipsSections": [ { "identifiers": [ "doc:\/\/bundle-id\/documentation\/CookpadMart\/ EmptyActivityLogger", "doc:\/\/bundle-id\/documentation\/CookpadMart\/ MartActivityLogger" ],

    "kind": "relationships", "title": "Conforming Types", "type": "conformingTypes" } ] { "primaryContentSections": [ ... ], "schemaVersion": { ... }, "sections": [], "variants": [ ... ], "relationshipsSections": [ ... ], "identifier": { ... }, "topicSections": [ ... ], "kind": "symbol", "metadata": { ... }, "hierarchy": { ... }, "references": { ... } }
  43. relationshipsSections • ґଘؔ܎ʹ͋ΔཁૉΛ ID ͰϦετΞοϓ • ࣗ਎͕ܧঝ͍ͯ͠Δɾ͞Ε͍ͯΔ class • ࣗ਎͕४ڌ͍ͯ͠Δɾ͞Ε͍ͯΔ

    protocol • ผϞδϡʔϧͷ΋ͷ΍ඪ४ϥΠϒϥϦͷ΋ͷ΋ࢀরͰ͖Δ → 💡 ґଘؔ܎ͷՄࢹԽʹ࢖͑ͦ͏
  44. ґଘؔ܎͕ݟ͑ΔͱԿ͕خ͍͔͠ • ϦϑΝΫλϦϯάͷͱ͖ʹͲ͜ʹӨڹ͕ग़Δ͔Λ೺ѲͰ͖Δ • ৽ϝϯόʔʹ৘ใڞ༗͢Δͱ͖ʹίʔυΛ௥͏ΑΓ؆୯

  45. Documentation Archive ͷ׆༻ ґଘؔ܎ΛՄࢹԽͯ͠ΈΔ

  46. ํ਑ • ు͖ग़͞Εͨ *.doccarchive ʹରͯ͠ҎԼΛ࣮ߦ͢Δ • ֤ json ͷ relationshipsSections

    Ωʔͷ஋Λࢀর͢Δ • identi fi ers Ωʔͷ஋͔Βґଘؔ܎ʹ͋ΔཁૉΛऔಘ͢Δ • type Ωʔͷ஋ΛΈ্ͯهཁૉͱ֘౰ͷཁૉͱͷؔ܎Λൈ͖ग़͢
  47. ࣮૷ • ҎԼͷ Ruby εΫϦϓτΛϓϩδΣΫτ಺Ͱ࣮ߦ͍ͯ͠·͢ • https://github.com/aomathwift/dependencies_generator

  48. ҰཡΛςΩετͷ··ग़ྗʢˢ͸ Markdown Ͱগ͠੔ܗʣ

  49. ಛఆͷཁૉʹର͢ΔґଘΛ PlantUML Ͱग़ྗ

  50. ࣮ࡍʹϓϩδΣΫτ಺Ͱ׆༻͢Δʹ͸ • ੒Ռ෺ΛϦϙδτϦ಺ʹ഑ஔ͠ɺࣗಈςετͰఆظతʹߋ৽͞ΕΔঢ় ଶʹ͢Δ • ੒Ռ෺ΛఆظతʹνʔϜͰோΊΔ࣌ؒΛ࡞Δ

  51. ͦͷଞͷσʔλ׆༻ߏ૝ • UIViewController Λܧঝ͍ͯ͠ΔΫϥεΛϦετΞοϓͯ͠ΞϓϦͷ ը໘ϦετΛ࡞Δ • conformingType ͷແ͍ protocol ͱ͔Λࣗಈݕ஌ͯ͠࡟আΛקΊΔΞ

    ϥʔτΛग़͢
  52. ·ͱΊ • Documentation Archive ͸ DocC υΩϡϝϯτΛ࡞Δͷʹඞཁͳཁૉ ͕٧Ίࠐ·Ε͍ͯͯ৘ใΛ༷ʑͳܗͰ׆༻Ͱ͖Δ • ΞϓϦͰͷ

    Swift-DocC ׆༻ͷՄೳੑ͸޿͕͍ͬͯΔ🚀