Slide 1
Slide 1 text
DocC Documentation Archive Λ
ΞϓϦ։ൃͰ׆༻ͯ͠ΈΑ͏
2022/09/28 After Party iOSDC Japan 2022 @aomathwift
Slide 2
Slide 2 text
ࣗݾհ
Aoi Okawa (@aomathwift)
Cookpad Inc. iOS Developer
Cookpad Mart
Slide 3
Slide 3 text
͓͜ͱΘΓ
• ͜ΕΞϓϦͷυΩϡϝϯτΛ DocC ʹஔ͖͑ͨͱ͍͏ࣄྫͷͰ
͋Γ·ͤΜ
• ΞϓϦέʔγϣϯλʔήοτͰ DocC Λॱʹѻ͏ํ๏ʹ͍ͭͯৄ
͘͠৮Ε·ͤΜ
• ͋͘·ͰݕূͱΞΠσΞͷͱͯ͠ฉ͍͍ͯͩ͘͞
Slide 4
Slide 4 text
Swift-DocC ͰͷυΩϡϝϯτ࡞
Slide 5
Slide 5 text
Swift-DocC ͱ
• Apple ७ਖ਼ͷυΩϡϝϯτ࡞πʔϧ
• Xcode 13 Ҏ߱ʹ౷߹
• OSS ͱͯ͠ެ։͞Ε͍ͯΔ
Slide 6
Slide 6 text
No content
Slide 7
Slide 7 text
Swift-DocC ͷΞοϓσʔτ
• Xcode 13.3 ͔ΒΞϓϦέʔγϣϯ͚ͷϏϧυΛαϙʔτ
• Github Pages ʹ؆୯ʹϗεςΟϯάͰ͖Δػೳ
→ ΞϓϦυΩϡϝϯτͷ DocC ԽΛקΊΔػӡʁ
Slide 8
Slide 8 text
ΞϓϦʹඞཁͳυΩϡϝϯτ
• ϓϩδΣΫτͷߏΞʔΩςΫνϟ
• CI / CD ʹ͍ͭͯ
• ։ൃϑϩʔ։ൃڥͷηοτΞοϓ
• Utility ΫϥεͷϝιουϓϩύςΟͷઆ໌
Slide 9
Slide 9 text
ΞϓϦʹඞཁͳυΩϡϝϯτ
• ϓϩδΣΫτͷߏΞʔΩςΫνϟ
• CI / CD ʹ͍ͭͯ
• ։ൃϑϩʔ։ൃڥͷηοτΞοϓ
• Utility ΫϥεͷϝιουϓϩύςΟͷઆ໌
→ Documentation Έ͍ͨͳσΟϨΫτϦԼʹஔ͍͍ͯΔ
Slide 10
Slide 10 text
ΞϓϦʹඞཁͳυΩϡϝϯτ
• ϓϩδΣΫτͷߏΞʔΩςΫνϟ
• CI / CD ʹ͍ͭͯ
• ։ൃϑϩʔ։ൃڥͷηοτΞοϓ
• Utility ΫϥεͷϝιουϓϩύςΟͷઆ໌
→ README.md CONTRIBUTING.md
Slide 11
Slide 11 text
No content
Slide 12
Slide 12 text
ΞϓϦʹඞཁͳυΩϡϝϯτ
• ϓϩδΣΫτͷߏΞʔΩςΫνϟ
• CI / CD ʹ͍ͭͯ
• ։ൃϑϩʔ։ൃڥͷηοτΞοϓ
• Utility ΫϥεͷϝιουϓϩύςΟͷઆ໌
→ ίʔυίϝϯτ = DocC ͷه๏Λར༻
Slide 13
Slide 13 text
ΞϓϦʹඞཁͳυΩϡϝϯτ
• ϓϩδΣΫτͷߏΞʔΩςΫνϟ
• CI / CD ʹ͍ͭͯ
• ։ൃϑϩʔ։ൃڥͷηοτΞοϓ
• Utility ΫϥεͷϝιουϓϩύςΟͷઆ໌
→ Documentation Catalog Λ͏
Slide 14
Slide 14 text
Documentation Catalog
•Markdownهࣄ֦ுϑΝΠϧΛ
ؚΊΔ͜ͱͰಛఆͷAPIͷઆ໌Ҏ֎
ͷ෦ͷυΩϡϝϯτΛิ
•ެࣜυΩϡϝϯτͷ Overview ͷ
ϖʔδ͕֘
Slide 15
Slide 15 text
͜͏͢Δͱ DocC ԽͰ͖Δ
• طଘͷ Markdown ϑΝΠϧΛ Documentation Catalog ʹೖΕࠐΉ
• ಛఆͷϝιουΫϥεͷઆ໌ DocC ίϝϯτΛॻ͖ࠐΉ
Slide 16
Slide 16 text
طଘͷυΩϡϝϯτͰݴ͏ͯࠔͬͯͳ͍
Ͱ DocC ͪΐͬͱ৮ͬͯΈ͍ͨͳ͊🥺
Slide 17
Slide 17 text
Documentation Archive ͱ͍͏ͷΛ༻͍ͯ
ผͷܗͰ Swift-DocC Λ׆༻ͯ͠Έ·͠ΐ͏
Slide 18
Slide 18 text
Agenda
• DocC Documentation Archive ͱ
• Documentation Archive ͷߏ
• Documentation Archive ͷ׆༻
Slide 19
Slide 19 text
Documentation Archive ͍ͭͯ
Slide 20
Slide 20 text
Documentation Archive
• *.doccarchive ֦ுࢠΛ࣋ͭυΩϡϝϯτͷຊମσΟϨΫτϦ
• Xcode Ͱ։͘ͱ DocC υΩϡϝϯτͱͯ͠ϨϯμϦϯά͞ΕΔ
Slide 21
Slide 21 text
No content
Slide 22
Slide 22 text
Documentation Archive ͷϏϧυ
• Xcode ͷ GUI ͔Β࣮ߦ
• Xcode ଐͷ doccbuild ίϚϯυͰ࣮ߦ
Slide 23
Slide 23 text
No content
Slide 24
Slide 24 text
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
Slide 25
Slide 25 text
Documentation Archive ͷߏ
Slide 26
Slide 26 text
No content
Slide 27
Slide 27 text
*.doccarchive
• υΩϡϝϯτΛϨϯμϦϯά͢Δͷʹඞཁͳใͷू·Γ
• Xcode13 ·Ͱ͜ͷσΟϨΫτϦΛϏϧυࡁΈυΩϡϝϯτ͔Β
Export Ͱ͖ͨ
※ Xcode14 ͔Β *.doccarchive/documentation ҎԼͷ HTML ϑΝΠ
ϧୡ͔͠ Export Ͱ͖ͳ͍
Slide 28
Slide 28 text
*.doccarhive/data
• ύʔε͞Εͨίϝϯτ͕ϝιουΫϥε͝ͱʹߏԽ͞Εͨͷ
• υΩϡϝϯτͷݟͨͲ͓ΓͷใΛ json ͷܗͰͭ
• {Target Name}.json ͕ϧʔτʹ͍Δ
Slide 29
Slide 29 text
{
"variants": [
...
],
"schemaVersion": {
...
},
"sections": [],
"identifier": {
...
},
"topicSections": [
...
],
"kind": "symbol",
"metadata": {
...
},
"hierarchy": {
...
},
"references": {
...
}
}
Slide 30
Slide 30 text
{Target Name}.json
• τοϓϖʔδใʹ͋ͨΔͷ
• topicSections
• Classes, Protocols, Structures, Variables, …
• references
• ֤ΫϥεͷυΩϡϝϯτͷIDද໊ࣔ
Slide 31
Slide 31 text
No content
Slide 32
Slide 32 text
"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": {
...
}
}
Slide 33
Slide 33 text
"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": {
...
}
}
Slide 34
Slide 34 text
֤ class ͝ͱͷϑΝΠϧɾσΟϨΫτϦ
• جຊతʹͦͷϖʔδͷυΩϡϝϯτʹฒΒΕΔηΫγϣϯͷใΛ
֤ηΫγϣϯ໊ͷΩʔʹͨͤΒΕ͍ͯΔ
• σΟϨΫτϦҎԼϝιουɾม͝ͱʹಉ༷ͷηΫγϣϯσʔλΛ
ͬͨ json ϑΝΠϧ͕٧Ίࠐ·Ε͍ͯΔ
Slide 35
Slide 35 text
{
"primaryContentSections": [
...
],
"schemaVersion": {
...
},
"sections": [],
"variants": [
...
],
"relationshipsSections": [
...
],
"identifier": {
...
},
"topicSections": [
...
],
"kind": "symbol",
"metadata": {
...
},
"hierarchy": {
...
},
"references": {
...
}
}
Slide 36
Slide 36 text
֤ class ͷϑΝΠϧ
• topicSections
• Initializers, Instance Properties, Instsnce Methods… ͳͲ
• primaryContentSections
• declaration ͳͲ
• relationshipsSections
• inheritFrom, conformTo, conformingType
Slide 37
Slide 37 text
No content
Slide 38
Slide 38 text
"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": {
...
}
}
Slide 39
Slide 39 text
No content
Slide 40
Slide 40 text
"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": {
...
}
}
Slide 41
Slide 41 text
No content
Slide 42
Slide 42 text
"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": {
...
}
}
Slide 43
Slide 43 text
relationshipsSections
• ґଘؔʹ͋ΔཁૉΛ ID ͰϦετΞοϓ
• ͕ࣗܧঝ͍ͯ͠Δɾ͞Ε͍ͯΔ class
• ͕ࣗ४ڌ͍ͯ͠Δɾ͞Ε͍ͯΔ protocol
• ผϞδϡʔϧͷͷඪ४ϥΠϒϥϦͷͷࢀরͰ͖Δ
→ 💡 ґଘؔͷՄࢹԽʹ͑ͦ͏
Slide 44
Slide 44 text
ґଘ͕ؔݟ͑ΔͱԿ͕خ͍͔͠
• ϦϑΝΫλϦϯάͷͱ͖ʹͲ͜ʹӨڹ͕ग़Δ͔ΛѲͰ͖Δ
• ৽ϝϯόʔʹใڞ༗͢Δͱ͖ʹίʔυΛ͏ΑΓ؆୯
Slide 45
Slide 45 text
Documentation Archive ͷ׆༻
ґଘؔΛՄࢹԽͯ͠ΈΔ
Slide 46
Slide 46 text
ํ
• ు͖ग़͞Εͨ *.doccarchive ʹରͯ͠ҎԼΛ࣮ߦ͢Δ
• ֤ json ͷ relationshipsSections ΩʔͷΛࢀর͢Δ
• identi
fi
ers Ωʔͷ͔Βґଘؔʹ͋ΔཁૉΛऔಘ͢Δ
• type ΩʔͷΛΈ্ͯهཁૉͱ֘ͷཁૉͱͷؔΛൈ͖ग़͢
Slide 47
Slide 47 text
࣮
• ҎԼͷ Ruby εΫϦϓτΛϓϩδΣΫτͰ࣮ߦ͍ͯ͠·͢
• https://github.com/aomathwift/dependencies_generator
Slide 48
Slide 48 text
ҰཡΛςΩετͷ··ग़ྗʢˢ Markdown Ͱগ͠ܗʣ
Slide 49
Slide 49 text
ಛఆͷཁૉʹର͢ΔґଘΛ PlantUML Ͱग़ྗ
Slide 50
Slide 50 text
࣮ࡍʹϓϩδΣΫτͰ׆༻͢Δʹ
• ՌΛϦϙδτϦʹஔ͠ɺࣗಈςετͰఆظతʹߋ৽͞ΕΔঢ়
ଶʹ͢Δ
• ՌΛఆظతʹνʔϜͰோΊΔ࣌ؒΛ࡞Δ
Slide 51
Slide 51 text
ͦͷଞͷσʔλ׆༻ߏ
• UIViewController Λܧঝ͍ͯ͠ΔΫϥεΛϦετΞοϓͯ͠ΞϓϦͷ
ը໘ϦετΛ࡞Δ
• conformingType ͷແ͍ protocol ͱ͔Λࣗಈݕͯ͠আΛקΊΔΞ
ϥʔτΛग़͢
Slide 52
Slide 52 text
·ͱΊ
• Documentation Archive DocC υΩϡϝϯτΛ࡞Δͷʹඞཁͳཁૉ
͕٧Ίࠐ·Ε͍ͯͯใΛ༷ʑͳܗͰ׆༻Ͱ͖Δ
• ΞϓϦͰͷ Swift-DocC ׆༻ͷՄೳੑ͕͍ͬͯΔ🚀