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

DocC Documentation Archive Λ

ΞϓϦ։ൃͰ׆༻ͯ͠ΈΑ͏
2022/09/28 After Party iOSDC Japan 2022 @aomathwift

View Slide

ࣗݾ঺հ
Aoi Okawa (@aomathwift)

Cookpad Inc. iOS Developer

Cookpad Mart

View Slide

͓͜ͱΘΓ
• ͜Ε͸ΞϓϦͷυΩϡϝϯτΛ DocC ʹஔ͖׵͑ͨͱ͍͏ࣄྫͷ࿩Ͱ
͸͋Γ·ͤΜ

• ΞϓϦέʔγϣϯλʔήοτͰ DocC Λॱ౰ʹѻ͏ํ๏ʹ͍ͭͯ͸ৄ
͘͠৮Ε·ͤΜ

• ͋͘·ͰݕূͱΞΠσΞͷ࿩ͱͯ͠ฉ͍͍ͯͩ͘͞

View Slide

Swift-DocC ͰͷυΩϡϝϯτ࡞੒

View Slide

Swift-DocC ͱ͸
• Apple ७ਖ਼ͷυΩϡϝϯτ࡞੒πʔϧ

• Xcode 13 Ҏ߱ʹ౷߹

• OSS ͱͯ͠΋ެ։͞Ε͍ͯΔ

View Slide

View Slide

Swift-DocC ͷΞοϓσʔτ
• Xcode 13.3 ͔ΒΞϓϦέʔγϣϯ޲͚ͷϏϧυΛαϙʔτ

• Github Pages ʹ؆୯ʹϗεςΟϯάͰ͖Δػೳ

→ ΞϓϦυΩϡϝϯτͷ DocC ԽΛקΊΔػӡʁ

View Slide

ΞϓϦʹඞཁͳυΩϡϝϯτ
• ϓϩδΣΫτͷߏ੒΍ΞʔΩςΫνϟ

• CI / CD ʹ͍ͭͯ

• ։ൃϑϩʔ΍։ൃ؀ڥͷηοτΞοϓ

• Utility Ϋϥεͷϝιου΍ϓϩύςΟͷઆ໌

View Slide





→ Documentation Έ͍ͨͳσΟϨΫτϦ഑Լʹஔ͍͍ͯΔ

View Slide





→ README.md ΍ CONTRIBUTING.md

View Slide

View Slide





→ ίʔυίϝϯτ = DocC ͷه๏Λར༻

View Slide





→ Documentation Catalog Λ࢖͏

View Slide

Documentation Catalog
•Markdownهࣄ΍֦ுϑΝΠϧΛ
ؚΊΔ͜ͱͰಛఆͷAPIͷઆ໌Ҏ֎
ͷ෦෼ͷυΩϡϝϯτΛิ׬

•ެࣜυΩϡϝϯτͷ Overview ͷ
ϖʔδ౳͕֘౰

View Slide

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

• ಛఆͷϝιου΍Ϋϥεͷઆ໌͸ DocC ίϝϯτΛॻ͖ࠐΉ

View Slide

طଘͷυΩϡϝϯτͰݴ͏ͯࠔͬͯͳ͍

Ͱ΋ DocC ͸ͪΐͬͱ৮ͬͯΈ͍ͨͳ͊🥺

View Slide

Documentation Archive ͱ͍͏΋ͷΛ༻͍ͯ

ผͷܗͰ Swift-DocC Λ׆༻ͯ͠Έ·͠ΐ͏

View Slide

Agenda
• DocC Documentation Archive ͱ͸

• Documentation Archive ͷߏ଄

• Documentation Archive ͷ׆༻

View Slide

Documentation Archive ͍ͭͯ

View Slide

Documentation Archive
• *.doccarchive ֦ுࢠΛ࣋ͭυΩϡϝϯτͷຊମσΟϨΫτϦ

• Xcode Ͱ։͘ͱ DocC υΩϡϝϯτͱͯ͠ϨϯμϦϯά͞ΕΔ

View Slide

View Slide

Documentation Archive ͷϏϧυ
• Xcode ͷ GUI ͔Β࣮ߦ

• Xcode ෇ଐͷ doccbuild ίϚϯυͰ࣮ߦ

View Slide

View Slide

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

View Slide

Documentation Archive ͷߏ଄

View Slide

View Slide

*.doccarchive
• υΩϡϝϯτΛϨϯμϦϯά͢Δͷʹඞཁͳ৘ใͷू·Γ

• Xcode13 ·Ͱ͸͜ͷσΟϨΫτϦΛϏϧυࡁΈυΩϡϝϯτ͔Β௚
઀ Export Ͱ͖ͨ

※ Xcode14 ͔Β͸ *.doccarchive/documentation ҎԼͷ HTML ϑΝΠ
ϧୡ͔͠ Export Ͱ͖ͳ͍

View Slide

*.doccarhive/data
• ύʔε͞Εͨίϝϯτ౳͕ϝιου΍Ϋϥε͝ͱʹߏ଄Խ͞Εͨ΋ͷ

• υΩϡϝϯτͷݟͨ໨Ͳ͓Γͷ৘ใΛ json ͷܗͰ΋ͭ

• {Target Name}.json ͕ϧʔτʹ͍Δ

View Slide

{

"variants": [

...

],

"schemaVersion": {

...

},

"sections": [],

"identifier": {

...

},

"topicSections": [

...

],

"kind": "symbol",

"metadata": {

...

},

"hierarchy": {

...

},

"references": {

...

}

}

View Slide

{Target Name}.json
• τοϓϖʔδ৘ใʹ͋ͨΔ΋ͷ

• topicSections

• Classes, Protocols, Structures, Variables, …

• references

• ֤Ϋϥε౳ͷυΩϡϝϯτͷID΍ද໊ࣔ

View Slide

View Slide

"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": {

...

}

}

View Slide

"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": {

...

}

}

View Slide

֤ class ͝ͱͷϑΝΠϧɾσΟϨΫτϦ
• جຊతʹͦͷϖʔδͷυΩϡϝϯτʹฒ΂ΒΕΔηΫγϣϯͷ৘ใΛ
֤ηΫγϣϯ໊ͷΩʔʹ΋ͨͤΒΕ͍ͯΔ

• σΟϨΫτϦҎԼ͸ϝιουɾม਺͝ͱʹಉ༷ͷηΫγϣϯσʔλΛ
΋ͬͨ json ϑΝΠϧ͕٧Ίࠐ·Ε͍ͯΔ

View Slide

{

"primaryContentSections": [

...

],

"schemaVersion": {

...

},

"sections": [],

"variants": [

...

],

"relationshipsSections": [

...

],

"identifier": {

...

},

"topicSections": [

...

],

"kind": "symbol",

"metadata": {

...

},

"hierarchy": {

...

},

"references": {

...

}

}

View Slide

֤ class ౳ͷϑΝΠϧ
• topicSections

• Initializers, Instance Properties, Instsnce Methods… ͳͲ

• primaryContentSections

• declaration ͳͲ

• relationshipsSections

• inheritFrom, conformTo, conformingType

View Slide

View Slide


{

"kind": "declarations",

"declarations": [

{

"tokens": [

{

"kind": "keyword",

"text": "protocol"

},

{

"kind": "text",

"text": " "

},

{

"kind": "identifier",

"text": "ActivityLogger"

}

],

"languages": [

"swift"

],

"platforms": [

"iOS"

]

}

]

}

]
{


...

],

"schemaVersion": {

...

},

"sections": [],

"variants": [

...

],


...

],

"identifier": {

...

},

"topicSections": [

...

],

"kind": "symbol",

"metadata": {

...

},

"hierarchy": {

...

},

"references": {

...

}

}

View Slide

View Slide

"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

}

]
{


...

],

"schemaVersion": {

...

},

"sections": [],

"variants": [

...

],


...

],

"identifier": {

...

},

"topicSections": [

...

],

"kind": "symbol",

"metadata": {

...

},

"hierarchy": {

...

},

"references": {

...

}

}

View Slide

View Slide


{

"identifiers": [

"doc:\/\/bundle-id\/documentation\/CookpadMart\/
EmptyActivityLogger",

"doc:\/\/bundle-id\/documentation\/CookpadMart\/
MartActivityLogger"

],

"kind": "relationships",

"title": "Conforming Types",

"type": "conformingTypes"

}

]
{


...

],

"schemaVersion": {

...

},

"sections": [],

"variants": [

...

],


...

],

"identifier": {

...

},

"topicSections": [

...

],

"kind": "symbol",

"metadata": {

...

},

"hierarchy": {

...

},

"references": {

...

}

}

View Slide

relationshipsSections
• ґଘؔ܎ʹ͋ΔཁૉΛ ID ͰϦετΞοϓ

• ࣗ਎͕ܧঝ͍ͯ͠Δɾ͞Ε͍ͯΔ class

• ࣗ਎͕४ڌ͍ͯ͠Δɾ͞Ε͍ͯΔ protocol

• ผϞδϡʔϧͷ΋ͷ΍ඪ४ϥΠϒϥϦͷ΋ͷ΋ࢀরͰ͖Δ

→ 💡 ґଘؔ܎ͷՄࢹԽʹ࢖͑ͦ͏

View Slide

ґଘؔ܎͕ݟ͑ΔͱԿ͕خ͍͔͠
• ϦϑΝΫλϦϯάͷͱ͖ʹͲ͜ʹӨڹ͕ग़Δ͔Λ೺ѲͰ͖Δ

• ৽ϝϯόʔʹ৘ใڞ༗͢Δͱ͖ʹίʔυΛ௥͏ΑΓ؆୯

View Slide

Documentation Archive ͷ׆༻

ґଘؔ܎ΛՄࢹԽͯ͠ΈΔ

View Slide

ํ਑
• ు͖ग़͞Εͨ *.doccarchive ʹରͯ͠ҎԼΛ࣮ߦ͢Δ

• ֤ json ͷ relationshipsSections Ωʔͷ஋Λࢀর͢Δ

• identi
fi
ers Ωʔͷ஋͔Βґଘؔ܎ʹ͋ΔཁૉΛऔಘ͢Δ

• type Ωʔͷ஋ΛΈ্ͯهཁૉͱ֘౰ͷཁૉͱͷؔ܎Λൈ͖ग़͢

View Slide

࣮૷
• ҎԼͷ Ruby εΫϦϓτΛϓϩδΣΫτ಺Ͱ࣮ߦ͍ͯ͠·͢

• https://github.com/aomathwift/dependencies_generator

View Slide

ҰཡΛςΩετͷ··ग़ྗʢˢ͸ Markdown Ͱগ͠੔ܗʣ

View Slide

ಛఆͷཁૉʹର͢ΔґଘΛ PlantUML Ͱग़ྗ

View Slide

࣮ࡍʹϓϩδΣΫτ಺Ͱ׆༻͢Δʹ͸
• ੒Ռ෺ΛϦϙδτϦ಺ʹ഑ஔ͠ɺࣗಈςετͰఆظతʹߋ৽͞ΕΔঢ়
ଶʹ͢Δ

• ੒Ռ෺ΛఆظతʹνʔϜͰோΊΔ࣌ؒΛ࡞Δ

View Slide

ͦͷଞͷσʔλ׆༻ߏ૝
• UIViewController Λܧঝ͍ͯ͠ΔΫϥεΛϦετΞοϓͯ͠ΞϓϦͷ
ը໘ϦετΛ࡞Δ

• conformingType ͷແ͍ protocol ͱ͔Λࣗಈݕ஌ͯ͠࡟আΛקΊΔΞ
ϥʔτΛग़͢

View Slide

·ͱΊ
• Documentation Archive ͸ DocC υΩϡϝϯτΛ࡞Δͷʹඞཁͳཁૉ
͕٧Ίࠐ·Ε͍ͯͯ৘ใΛ༷ʑͳܗͰ׆༻Ͱ͖Δ

• ΞϓϦͰͷ Swift-DocC ׆༻ͷՄೳੑ͸޿͕͍ͬͯΔ🚀

View Slide

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

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

aoi

More Decks by aoi

Other Decks in Technology

Featured

Transcript