What's new in Swift-DocC

♪ Mellow instrumental hip-hop music ♪ ♪ Franklin Schrans: Hello, my name is Franklin, and I'm an engineer on the Swift-DocC team. Together with my colleague Ethan, I'm excited to give you a tour of Swift-DocC in Xcode 14, packed with great new tools to help you create even better documentation. We introduced Swift-DocC last year in Xcode 13, allowing you to guide developers through your Swift frameworks. With Swift-DocC, you write comprehensive content, from reference documentation for individual APIs to conceptual articles that provide a higher-level story for using these APIs together, all the way to step-by-step tutorials that walk the user through a task. This year, with Xcode 14, Swift-DocC unlocks brand-new, exciting workflows. In addition to documenting frameworks, we're thrilled to now support app projects as well, so that you can easily collaborate with your team. You can now also document Objective-C and C APIs using Swift-DocC, allowing you to describe all your project's APIs together. Publishing your content to a website is now dramatically easier, with out-of-the-box support for static hosting environments like GitHub Pages. And thanks to the powerful new navigation sidebar, developers will be able to discover your content easier than ever before. Also, with Swift-DocC now being an open source project, these new features were developed in close collaboration with the open source community. In this session, we'll take a tour of Swift-DocC and the exciting new workflows it unlocks in Xcode 14. First, we'll discover how to document your project's APIs right inline with your source code. Then, we'll take a look at seamlessly publishing your content to a website. And finally, we'll discover the brand-new navigation sidebar on the web. Let's start with writing documentation. Good documentation is essential to any software project. As your project evolves, it's important to describe its functionality and design so that developers have a solid reference point when contributing. Swift-DocC in Xcode gives you the tools you need to create fantastic documentation, using the same tools you use to develop code. And this year, we're excited to expand Swift-DocC to app projects. Let's dive right in. We'll document an app I'm working on with my team called Slothy, which contains both Swift and Objective-C source files. Even with a brand-new project, where I haven't written documentation yet, you can open the Product menu and select Build Documentation, and Xcode opens the documentation window, where you'll see stubs that Swift-DocC automatically generates for your APIs. This provides a great starting point for filling in these pages to help contributors navigate the project. So, let's take it step by step to turn this content into a rich and complete guide for contributing to our app. A good place to start is to teach how each API works individually, and from there, to provide higher-level content using a documentation catalog. Let's start by describing a view called SlothView. For this documentation to be visible to Swift-DocC, start your comment using three slashes. Then, add a concise summary for your view. In the built documentation page, this translates to text displayed prominently right below the view's name. Then, add more details using additional paragraphs. This content appears in the Overview section of the page. And use Swift-DocC's link syntax to turn references to APIs into active links, allowing you to quickly jump to Pages to learn more. DocC even validates these links when you build, so you get warnings if they go out of date. Finally, if you wish to provide an example of how to use this view, add a code listing using the Markdown code block syntax. Now, contributors know at a glance how to use this view. In just a few steps, my view's documentation is now much more helpful to contributors of this project. Next up, let's document an initializer. Again, start by writing a summary. For initializers and methods, it's a good idea to describe each parameter individually. You do so by adding a parameter list item, with a short description of what the parameter is. Notice how the content appears in a separate Parameters section. Now let's take a look at the Objective-C APIs defined in this project. New in Xcode 14, we're excited to bring Swift-DocC's comprehensive tooling to document Objective-C code. Using the same familiar Markdown syntax you know and love, and updated support in Xcode's source editor, you can now describe and organize all your project's APIs together. And for code that can be called from both Swift and Objective-C, there's a nifty language toggle to browse the page in the language you're coding in. Check out the developer documentation linked below for more details. Now, let's apply this to our Slothy project. I'll describe the SLOSound class and its initializer. Notice that because this class can be used from both Swift and Objective-C code, Xcode displays a language toggle allowing you to browse the content in the language you're using. Let's describe the class and initializer using the same Markdown syntax you use for Swift code. Great, this looks much better. I've added a summary, an overview, and for the initializer, a parameters section. And that wraps up describing individual APIs. By writing a few documentation comments in source code, developers contributing to my project have a better understanding of how to use its APIs. Now, let's focus on creating a great top-level page for our app. This is the first page contributors will see, so I'd like to provide a great introduction to what the app does and how to contribute to it. To customize the top-level page, start by adding a documentation catalog. To do so, right-click on your project's source folder and select New File. Then select Documentation Catalog. A Documentation Catalog complements your source code documentation and contains additional Markdown files and media. Xcode automatically adds a file for the top-level page of your app. Let's fill it in with an overview of what the app does. Using the same syntax you use for documentation comments in source code, I added a summary, an overview, and even embedded rich content like images. Great, this looks much more inviting. Now contributors know at a glance what my app is about. And that's it! I've dramatically improved documentation for my app and provided a great reference point to my project's contributors. They can browse the top-level page for an overview of the project, and jump into each page to get detailed information about each of its APIs. Now that we've seen how to write and build documentation, it's time to publish it to a website so that contributors can easily browse it. Over to you, Ethan. Ethan Kusters: Thank you, Franklin. We've been developing the Slothy app in a modular way alongside a more generally useful Swift Package called SlothCreator. I think it would be great to publish SlothCreator to a wider audience so that other developers making sloth-related apps can make use of it. As a part of this effort, I want to be sure SlothCreator's documentation is easily shareable on the web, so let's walk through Swift-DocC's brand-new, simplified publishing workflow. When you build documentation in Xcode, Swift-DocC produces a static bundle containing your documentation. This bundle is called a DocC archive and is a portable container for your documentation. You can export it directly from Xcode's documentation window and send it to colleagues. They'll be able to open and browse the documentation by just double-clicking on the archive. But a DocC archive isn't just a portable container for opening documentation in Xcode. It also contains a fully featured website right out of the box. And new in Xcode 14, that DocC archive is also directly compatible with most web servers. This makes publishing your documentation to the web easier than ever. In most cases, you can deploy your documentation by just copying the contents of your built DocC archive into the root of your web server. This also means that DocC archives are now compatible with most managed hosting services, including GitHub Pages. GitHub Pages is a popular way many developers host their documentation that's integrated right into GitHub.com. And since we've been using GitHub for the source control of SlothCreator, it makes sense for us to publish our documentation there as well. If you're familiar with using GitHub pages, you'll know that, unlike a standard server, your website is not published at the root path of the URL but at a specific base path. In this kind of hosting scenario, you'll need to specify your website's base path with an additional build setting to produce a DocC archive that's compatible. To fully understand how this works and why we only need this configuration in certain hosting scenarios -- like on GitHub Pages -- let's take a look at how we would expect the URL of a DocC archive hosted on your own domain might look. Let's assume we already have a website for the Slothy app -- slothy.example.com -- and we'd like to publish the documentation for SlothCreator as a part of that existing website. If we just take the content of the SlothCreator DocC archive and copy it to the root of our web server, the reference documentation for SlothCreator will appear at slothy.example.com/ documentation/slothcreator. Any tutorials for the SlothCreator package would be at a neighboring "tutorials" path. However, in this case, we're not going to be publishing to our own domain. Instead, to keep the documentation with our GitHub repository, we'll publish to the domain GitHub Pages provides. When you create a GitHub Pages site for a repository, the URL of that website is not at the root path; instead, it's at a specific base path corresponding to the name of the repository. Generally that will be something like your username.github.io forward-slash your repository name. Any reference and tutorial documentation paths are appended to that base path. Because this base path is unique to your repository, it's important to tell Swift-DocC what it is before building a DocC archive for publishing to GitHub Pages. There's a new build setting exposed in Xcode 14 for just this use case. After configuring the DocC Archive Hosting Base Path setting to be the name of your GitHub repository, you'll be ready to go for all of your future documentation builds. Let's take a look at how this works in practice. Here, I've opened the SlothCreator Swift package Franklin showed you earlier as a dependency of the Slothy app. Since we're getting close to publishing this package for wider use, I'm going to go ahead and publish the documentation we've prepared to GitHub Pages. I'll begin by opening the framework's project settings by moving my mouse to Xcode's Project navigator and selecting the SlothCreator item. Next, I'll select the SlothCreator target, and then open the Build Settings tab. In this case, I'm looking for a Swift-DocC-related setting, so let's filter for DocC. Now I'll set the DocC Archive Hosting Base Path setting to be the name of our repository: sloth-creator. Great! Next, let's build documentation. I'll move my mouse up to the Product menu and select Build documentation. After Xcode finishes compiling my project and generating documentation for it, the documentation window will open. Here's the top-level page for SlothCreator's documentation. Let's go ahead and export it. I'll move my mouse over to the documentation navigator and the SlothCreator technology item. Next I'll click on the context menu and select Export. I'm going to export it to a directory named "docs" in the root of my repository because this is how I've configured GitHub Pages to publish my documentation website.

Now I just need to commit and push my changes up to GitHub. Back in the main Xcode window, I'll move my mouse up to the Source Control menu and select Commit. I'll select the docs directory that has my documentation content and write a commit message. Let's go ahead and push the changes.

And that's it. Let's go check out the published site. I'll open up my repository on GitHub.com.

I'd already placed a link to the documentation site in the README, so I'll just click on it. And here we are. I'm so excited to have the documentation we worked on for SlothCreator easily accessible on the web. I think this is going to be really helpful for folks interested in using SlothCreator in their own projects. Now that we've deployed the documentation for SlothCreator once, I'd really like to set up automation to perform a deployment any time the documentation in the repository changes. Since we're releasing SlothCreator as a Swift Package, the new Swift-DocC Swift Package Manager plug-in is going to be a great help here. You can use the Swift-DocC plug-in to really simplify the process of building documentation for Swift packages. The plug-in's documentation is linked below and I recommend checking it out as a great starting place for configuring automated documentation deployments to GitHub Pages and other hosting services. And of course, Swift-DocC continues to have great command-line support for Xcode projects with the xcodebuild docbuild command-line interface that was introduced in Xcode 13. Documentation for how to get started using xcodebuild to automate GitHub Pages deployments is linked below. We're thrilled to be releasing an all-new enhanced browsing and navigation experience for Swift-DocC on the web this year. Let's take a look at how the new navigation sidebar can help readers of the SlothCreator documentation explore what the framework has to offer. We're back on the GitHub Pages site for SlothCreator, and over on the left side of the page is the new navigation sidebar. I'll move my mouse over to the CareSchedule item and expand it by clicking on the disclosure triangle. Now I can see the pages that are organized as children of CareSchedule without even needing to fully open the page. In this case, I'm interested in jumping straight to the type's initializer. I can continue navigating through the framework, expanding other items like FoodGenerator and SlothFood, eventually opening the twig page. As I'm navigating between pages, the state of the navigation sidebar stays constant, allowing me to keep track of the pages I've already visited. This allows for a natural exploration of the framework that I really appreciate. But what if I'm already familiar with the SlothCreator framework and am looking for information about a specific symbol? The filter field at the bottom of the new navigation sidebar is perfect for this. I'm interested in an API that will help me increase the energy level of my sloths. I'll move my mouse to the bottom of the navigator, select the filter bar, and insert "energy." Perfect! This documentation on the energyLevel property is exactly what I was looking for. The new browsing experience offered by Swift-DocC in Xcode 14 is going to bring your documentation site to the next level. We're so excited for you to try it out. Swift-DocC's integration in Xcode now offers support for documenting all of your projects. This includes your Objective-C and Swift code in application and framework targets, whether packaged as Xcode projects or Swift Packages. The DocC archive produced by Xcode 14 is immediately compatible with popular hosting services, including GitHub Pages. This is a game changer for distributing your documentation to an even wider audience. And finally, Swift-DocC offers a powerful new navigation experience on the web. The navigation sidebar is going to unlock new ways of exploring and finding the documentation on your site. To learn more about the new Swift-DocC sidebar and how to best author your documentation to take advantage of its new features, check out the "Improve the discoverability of your Swift-DocC content" session. And to take your documentation even further, check out the "Build interactive tutorials using DocC" session to learn how to build step-by-step walk-throughs to guide developers through your app or framework. We are so excited to see all of the documentation you write and publish with Xcode 14. Thank you for watching. ♪