Save 37% off PRO during our Black Friday Sale! »

Navigating DocC - Mobiconf, Online, October 2021

Navigating DocC - Mobiconf, Online, October 2021

Apple introduced a new documentation framework at WWDC called DocC. Learn more about how it works, how it helps reinforce best practices for inline documentation, and how you can use it to level up both documentation and tutorials for your framework.

C4861b1dfdf3bbb21faec4a1acdf183d?s=128

Ellen Shapiro
PRO

October 08, 2021
Tweet

Transcript

  1. ! Navigating DocC Mobiconf | The Internets | October 2021

    Ellen Shapiro | @DesignatedNerd | ApolloGraphQL.com @DesignatedNerd
  2. None
  3. None
  4. ! @DesignatedNerd

  5. @DesignatedNerd

  6. DocC @DesignatedNerd

  7. via instagram.com/sailor.moon.doxie

  8. ! via instagram.com/sailor.moon.doxie

  9. @DesignatedNerd

  10. ! @DesignatedNerd

  11. Doc @DesignatedNerd

  12. Doc C @DesignatedNerd

  13. !" @DesignatedNerd

  14. @DesignatedNerd

  15. @DesignatedNerd

  16. @DesignatedNerd

  17. @DesignatedNerd

  18. ! @DesignatedNerd

  19. @DesignatedNerd

  20. Where do I start? @DesignatedNerd

  21. You probably already did @DesignatedNerd

  22. /// Finds the parent folder from a given file path.

    /// /// - Parameter filePath: The full file path, as a string /// - Returns: The file URL for the parent folder. public static func findParentFolder(from filePath: String) -> URL { let url = URL(fileURLWithPath: filePath) return url.deletingLastPathComponent() } @DesignatedNerd
  23. /// Finds the parent folder from a given file path.

    /// /// - Parameter filePath: The full file path, as a string /// - Returns: The file URL for the parent folder. public static func findParentFolder(from filePath: String) -> URL { let url = URL(fileURLWithPath: filePath) return url.deletingLastPathComponent() } @DesignatedNerd
  24. /** Finds the parent folder from a given file path.

    Parameter filePath: The full file path, as a string Returns: The file URL for the parent folder. */ public static func findParentFolder(from filePath: String) -> URL { let url = URL(fileURLWithPath: filePath) return url.deletingLastPathComponent() } @DesignatedNerd
  25. None
  26. @DesignatedNerd

  27. @DesignatedNerd

  28. @DesignatedNerd

  29. Part 1: Fancifying Swift Documentation @DesignatedNerd

  30. Symbol `` Links `` @DesignatedNerd

  31. @DesignatedNerd

  32. @DesignatedNerd

  33. @DesignatedNerd

  34. @DesignatedNerd

  35. @DesignatedNerd

  36. @DesignatedNerd

  37. @DesignatedNerd

  38. @DesignatedNerd

  39. @DesignatedNerd

  40. @DesignatedNerd

  41. @DesignatedNerd

  42. @DesignatedNerd

  43. @DesignatedNerd

  44. @DesignatedNerd

  45. @DesignatedNerd

  46. Limitations @DesignatedNerd

  47. Limitations (at least for now) @DesignatedNerd

  48. Frameworks Packages Applications @DesignatedNerd

  49. Frameworks Packages Applications @DesignatedNerd

  50. Frameworks Packages Applications @DesignatedNerd

  51. Frameworks Packages Applications @DesignatedNerd

  52. ! Linking to Related Frameworks @DesignatedNerd

  53. → Classes → Structs → Enums → Protocols → Free

    Functions → Type Aliases → Custom Operators → Extensions of types outside your framework @DesignatedNerd
  54. → Classes → Structs → Enums → Protocols → Free

    Functions → Type Aliases → Custom Operators → Extensions of types outside your framework @DesignatedNerd
  55. → Classes → Structs → Enums → Protocols → Free

    Functions → Type Aliases → Custom Operators → Extensions of types outside your framework @DesignatedNerd
  56. extension String { /// An extrmely secure cryptographic function ///

    /// - Returns: The reciever, encrypted. public func customEncryption() -> String { return String(self.reversed()) } } @DesignatedNerd
  57. public extension String { /// An extrmely secure cryptographic function

    /// /// - Returns: The reciever, encrypted. func customEncryption() -> String { return String(self.reversed()) } } @DesignatedNerd
  58. @DesignatedNerd

  59. @DesignatedNerd

  60. @DesignatedNerd

  61. @DesignatedNerd

  62. @DesignatedNerd

  63. @DesignatedNerd

  64. @DesignatedNerd

  65. @DesignatedNerd

  66. @DesignatedNerd

  67. Will be open-sourced "Later this year" @DesignatedNerd

  68. (Assume this means December 31) @DesignatedNerd

  69. @DesignatedNerd

  70. @DesignatedNerd

  71. DoccZz @DesignatedNerd

  72. https://github.com/DoccZz/servedocc @DesignatedNerd

  73. @DesignatedNerd

  74. @DesignatedNerd

  75. @DesignatedNerd

  76. @DesignatedNerd

  77. https://github.com/DoccZz/docc2html @DesignatedNerd

  78. @DesignatedNerd

  79. @DesignatedNerd

  80. @DesignatedNerd

  81. Part 2: Better Information ! Architecture @DesignatedNerd

  82. @DesignatedNerd

  83. @DesignatedNerd

  84. Documentation Catalog @DesignatedNerd

  85. @DesignatedNerd

  86. @DesignatedNerd

  87. @DesignatedNerd

  88. @DesignatedNerd

  89. @DesignatedNerd

  90. @DesignatedNerd

  91. @DesignatedNerd

  92. ಠ_ಠ @DesignatedNerd

  93. @DesignatedNerd

  94. @DesignatedNerd

  95. @DesignatedNerd

  96. @DesignatedNerd

  97. @DesignatedNerd

  98. @DesignatedNerd

  99. @DesignatedNerd

  100. @DesignatedNerd

  101. @DesignatedNerd

  102. @DesignatedNerd

  103. @DesignatedNerd

  104. @DesignatedNerd

  105. @DesignatedNerd

  106. @DesignatedNerd

  107. @DesignatedNerd

  108. @DesignatedNerd

  109. Articles @DesignatedNerd

  110. @DesignatedNerd

  111. @DesignatedNerd

  112. @DesignatedNerd

  113. Put long doc discussions into dedicated files @DesignatedNerd

  114. @DesignatedNerd

  115. @DesignatedNerd

  116. Part 3: ✨ Shiny Tutorials @DesignatedNerd

  117. @DesignatedNerd

  118. Markdown Directives @DesignatedNerd

  119. @Tutorials(name: "Working With Apollo iOS") { @Intro(title: "Welcome!") { This

    tutorial will walk you through using the Apollo iOS SDK to communicate with your GraphQL server. } @Chapter(name: "Setup") { This chapter allows you to pick a tutorial based on which package manager you use. @Image(source: full-logo, alt: "Apollo logo") @TutorialReference(tutorial: "doc:SwiftPMSetup") @TutorialReference(tutorial: "doc:CocoapodsSetup") @TutorialReference(tutorial: "doc:CarthageSetup") } } @DesignatedNerd
  120. @DesignatedNerd

  121. @DesignatedNerd

  122. @Tutorials(name: "Working With Apollo iOS") { @Intro(title: "Welcome!") { This

    tutorial will walk you through using the Apollo iOS SDK to communicate with your GraphQL server. } @Chapter(name: "Setup") { This chapter allows you to pick a tutorial based on which package manager you use. @Image(source: full-logo, alt: "Apollo logo") @TutorialReference(tutorial: "doc:SwiftPMSetup") @TutorialReference(tutorial: "doc:CocoapodsSetup") @TutorialReference(tutorial: "doc:CarthageSetup") } } @DesignatedNerd
  123. @Tutorials(name: "Working With Apollo iOS") { @Intro(title: "Welcome!") { This

    tutorial will walk you through using the Apollo iOS SDK to communicate with your GraphQL server. } @Chapter(name: "Setup") { This chapter allows you to pick a tutorial based on which package manager you use. @Image(source: full-logo, alt: "Apollo logo") @TutorialReference(tutorial: "doc:SwiftPMSetup") @TutorialReference(tutorial: "doc:CocoapodsSetup") @TutorialReference(tutorial: "doc:CarthageSetup") } } @DesignatedNerd
  124. @Tutorials(name: "Working With Apollo iOS") { @Intro(title: "Welcome!") { This

    tutorial will walk you through using the Apollo iOS SDK to communicate with your GraphQL server. } @Chapter(name: "Setup") { This chapter allows you to pick a tutorial based on which package manager you use. @Image(source: full-logo, alt: "Apollo logo") @TutorialReference(tutorial: "doc:SwiftPMSetup") @TutorialReference(tutorial: "doc:CocoapodsSetup") @TutorialReference(tutorial: "doc:CarthageSetup") } } @DesignatedNerd
  125. @Tutorials(name: "Working With Apollo iOS") { @Intro(title: "Welcome!") { This

    tutorial will walk you through using the Apollo iOS SDK to communicate with your GraphQL server. } @Chapter(name: "Setup") { This chapter allows you to pick a tutorial based on which package manager you use. @Image(source: full-logo, alt: "Apollo logo") @TutorialReference(tutorial: "doc:SwiftPMSetup") @TutorialReference(tutorial: "doc:CocoapodsSetup") @TutorialReference(tutorial: "doc:CarthageSetup") } } @DesignatedNerd
  126. @DesignatedNerd

  127. @Tutorial(time: 15) { @Intro(title: "Getting Set Up with Swift Package

    Manager") { This is how you get setup with SPM } @Section(title: "Using Xcode to Add via SwiftPM") { @ContentAndMedia { Xcode has built in support for Swift Package Manager, and you can use it to add Apollo to your project. } @Steps { @Step { Select the `xcodeproj` in your project navigator. @Image(source:select-package-and-project, alt: "The xcodeproj file in the navigator") } @Step { Select the "Package Dependencies" tab. } ... } } } @DesignatedNerd
  128. @Tutorial(time: 15) { @Intro(title: "Getting Set Up with Swift Package

    Manager") { This is how you get setup with SPM } @Section(title: "Using Xcode to Add via SwiftPM") { @ContentAndMedia { Xcode has built in support for Swift Package Manager, and you can use it to add Apollo to your project. } @Steps { @Step { Select the `xcodeproj` in your project navigator. @Image(source:select-package-and-project, alt: "The xcodeproj file in the navigator") } @Step { Select the "Package Dependencies" tab. } ... } } } @DesignatedNerd
  129. @DesignatedNerd

  130. @Tutorial(time: 15) { @Intro(title: "Getting Set Up with Swift Package

    Manager") { This is how you get setup with SPM } @Section(title: "Using Xcode to Add via SwiftPM") { @ContentAndMedia { Xcode has built in support for Swift Package Manager, and you can use it to add Apollo to your project. } @Steps { @Step { Select the `xcodeproj` in your project navigator. @Image(source:select-package-and-project, alt: "The xcodeproj file in the navigator") } @Step { Select the "Package Dependencies" tab. } ... } } } @DesignatedNerd
  131. @Tutorial(time: 15) { @Intro(title: "Getting Set Up with Swift Package

    Manager") { This is how you get setup with SPM } @Section(title: "Using Xcode to Add via SwiftPM") { @ContentAndMedia { Xcode has built in support for Swift Package Manager, and you can use it to add Apollo to your project. } @Steps { @Step { Select the `xcodeproj` in your project navigator. @Image(source:select-package-and-project, alt: "The xcodeproj file in the navigator") } @Step { Select the "Package Dependencies" tab. } ... } } } @DesignatedNerd
  132. @Tutorial(time: 15) { @Intro(title: "Getting Set Up with Swift Package

    Manager") { This is how you get setup with SPM } @Section(title: "Using Xcode to Add via SwiftPM") { @ContentAndMedia { Xcode has built in support for Swift Package Manager, and you can use it to add Apollo to your project. } @Steps { @Step { Select the `xcodeproj` in your project navigator. @Image(source:select-package-and-project, alt: "The xcodeproj file in the navigator") } @Step { Select the "Package Dependencies" tab. } ... } } } @DesignatedNerd
  133. @Tutorial(time: 15) { @Intro(title: "Getting Set Up with Swift Package

    Manager") { This is how you get setup with SPM } @Section(title: "Using Xcode to Add via SwiftPM") { @ContentAndMedia { Xcode has built in support for Swift Package Manager, and you can use it to add Apollo to your project. } @Steps { @Step { Select the `xcodeproj` in your project navigator. @Image(source:select-package-and-project, alt: "The xcodeproj file in the navigator") } @Step { Select the "Package Dependencies" tab. } ... } } } @DesignatedNerd
  134. @DesignatedNerd

  135. ! @DesignatedNerd

  136. https://www.jessesquires.com/blog/2021/06/29/apple-docc-great-but-useless-for-oss/

  137. Who is Apple building this tool for? @DesignatedNerd

  138. Who is Apple building this tool for? → Themselves @DesignatedNerd

  139. Who is Apple building this tool for? → Themselves →

    People who don't have a lot of resources but still want to make good documentation @DesignatedNerd
  140. DocC v1 @DesignatedNerd

  141. @DesignatedNerd

  142. Obligatory Summary Slide @DesignatedNerd

  143. Obligatory Summary Slide → DocC uses Swift Compiler to make

    your docs shiny @DesignatedNerd
  144. Obligatory Summary Slide → DocC uses Swift Compiler to make

    your docs shiny → Inline documentation is a huge part of the battle @DesignatedNerd
  145. Obligatory Summary Slide → DocC uses Swift Compiler to make

    your docs shiny → Inline documentation is a huge part of the battle → Use a Documentation Catalog to add structure @DesignatedNerd
  146. Obligatory Summary Slide → DocC uses Swift Compiler to make

    your docs shiny → Inline documentation is a huge part of the battle → Use a Documentation Catalog to add structure → Architect your info to be easier to understand @DesignatedNerd
  147. Obligatory Summary Slide → DocC uses Swift Compiler to make

    your docs shiny → Inline documentation is a huge part of the battle → Use a Documentation Catalog to add structure → Architect your info to be easier to understand → Tutorials are shiny but a lot of work @DesignatedNerd
  148. Obligatory Summary Slide → DocC uses Swift Compiler to make

    your docs shiny → Inline documentation is a huge part of the battle → Use a Documentation Catalog to add structure → Architect your info to be easier to understand → Tutorials are shiny but a lot of work → File Radars Feedback! @DesignatedNerd
  149. Thank you! @DesignatedNerd

  150. Links! → DocC, Archived and Analyzed https:// www.alwaysrightinstitute.com/docz/ → How

    to Document Your Project With DocC https:// www.hackingwithswift.com/articles/238/how-to- document-your-project-with-docc @DesignatedNerd
  151. Links! → Documenting a Swift Framework or Package https://developer.apple.com/documentation/ Xcode/documenting-a-swift-framework-or-

    package → Formatting Your Documentation Content https:// developer.apple.com/documentation/xcode/ formatting-your-documentation-content @DesignatedNerd