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

https://cookpad.connpass.com/event/254459/

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 ͱͯ͠΋ެ։͞Ε͍ͯΔ
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
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 υΩϡϝϯτͱͯ͠ϨϯμϦϯά͞ΕΔ
22. Documentation Archive ͷϏϧυ • Xcode ͷ GUI ͔Β࣮ߦ • Xcode ෇ଐͷ doccbuild ίϚϯυͰ࣮ߦ
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 ͷߏ଄
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΍ද໊ࣔ
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
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": { ... } }
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": { ... } }
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 ׆༻ͷՄೳੑ͸޿͕͍ͬͯΔ🚀