Create rich documentation with Swift-DocC

♪ ♪ Ethan: Hello! And welcome to "Create rich documentation with Swift-DocC". I'm Ethan, an engineer on the Swift-DocC team. Xcode 15 brings all new capabilities to your Swift-DocC documentation that will not only make your documentation stand out, but also give you more effective tools for teaching your reader about your app or framework. And with Xcode 15's brand new Documentation Preview editor, you'll be able to iterate on your documentation without ever leaving the Source editor. I can't wait to show it to you. Let's start with a quick overview of Swift-DocC. Swift-DocC is a documentation compiler integrated directly into Xcode that allows you to write and publish rich documentation for your project right alongside your source code. You use a mix of documentation comments written directly in-source and standalone Markdown files to write both high-level conceptual content and detailed technical documentation. This documentation is compatible out-of-the-box with static web hosting solutions, allowing straightforward publishing to services like GitHub Pages and Netlify. And of course, your documentation will also appear in Xcode's built-in documentation window and integrate into Xcode's Source editor with Quick Help. This means that the documentation you write will be automatically available to anyone who has access to your source code, without any additional work on your end. Since the release of Swift-DocC in Xcode 13, the Swift-DocC project has been open sourced and is now developed in the open. We've worked with the Swift community to add support for documenting all of your projects, including support for both apps and frameworks whether written in Swift, Objective-C, or even a mix of the two. Xcode 15 brings the experience of writing Swift-DocC documentation to a whole new level. The Documentation Preview editor gives you a real-time view of the rendered version of your documentation as you type, providing feedback with every keystroke. And with brand-new authoring capabilities like grid-based layouts, video support, custom page icons, and even fully custom themes, you can craft truly bespoke documentation that really advocates for your project. This session will focus on some more advanced capabilities of Swift-DocC. So if this is your first time learning about Swift-DocC, I’d recommend first watching "Meet DocC documentation in Xcode" and "Elevate your DocC documentation in Xcode". These two sessions introduce the framework that we'll be improving the documentation for today and guide you through the process of adding your first pieces of documentation to a brand-new project.

We'll begin today by covering a new workflow for writing documentation with Xcode 15's Documentation Preview editor. We'll use the new editor as we take advantage of some new Swift-DocC capabilities to enhance the existing documentation for a framework. Next, we'll create a custom theme for the documentation so that the web version looks right at home with an existing website. Finally, after publishing the documentation to the web, we'll take a tour of the brand new navigation capabilities coming to all Swift-DocC websites with Xcode 15. Let's dive right in.

Over the last couple of years, my teammates and I have been working on a Swift package called SlothCreator. SlothCreator is a framework that can be imported into iOS apps and used to catalog, customize, and display little sloths. We want SlothCreator to be used in more iOS apps so we've been looking at ways we can improve its documentation. I've opened the SlothCreator Swift package in Xcode 15. Let's begin by evaluating the current state of its documentation. I'll move my mouse to the Product menu and select Build Documentation.

Xcode will build my project along with its documentation and then open the documentation window. This is something you can try in your own projects, even if you haven't written any documentation specifically for Swift-DocC. Swift-DocC automatically creates pages for the relevant API in your project, including any documentation comments you may have written for them, so you might be surprised by how helpful the documentation is right out-of-the-box. And even better, when you select Build Documentation, Xcode will also produce documentation for all of your project's dependencies, so if you depend on any third-party libraries, like SlothCreator for example, these will appear as well. Here's SlothCreator's top-level documentation page. It begins with a summary sentence and then an overview of what the framework is all about. I'll scroll down the page a little to the Topics section. Topics are used to organize the different pages of your documentation into logical groups. First we have Essentials which contains introductory documentation for newcomers to the framework. Then there's a group containing symbols that help with sloth creation, with caring and feeding for sloths, and so on. Well-organized topic groups are key to creating discoverable and accessible documentation for your project. I'd recommend watching "Improve the discoverability of your Swift-DocC content" to learn about some advanced techniques to help readers browse your documentation with ease. Let's open the documentation for the Sloth structure. I'll click on it now.

Sloth is really well-documented with a good overview that contains inline links to relevant pages, a code example to get me started, and well-organized Topic groups that help in discovering related symbols. I'll use the back button to navigate back to the top-level page for SlothCreator. And I'll continue scrolling down the page. I'm really happy with how things are organized here. But at the very bottom of the page, I'm actually seeing a symbol that I haven't seen before, the SwiftUI module. Well, it turns out that this symbol is appearing because of a new Swift-DocC feature in Xcode 15, extension support. With Xcode 15, you can now document the extensions you make to types that belong to other frameworks. Extensions are a powerful Swift language feature that allow you to add functionality to a type that you may not have access to the original source code for. For example, you might extend SwiftUI's View protocol to include some additional functionality for your app. Now you can document those extension symbols right alongside the rest of your app or framework. This new functionality was entirely driven by community contributions and involved coordinated changes across both Swift-DocC and the Swift compiler. Let's see how we can take advantage of it here to improve the documentation for SlothCreator. I'll click on the SwiftUI extended module now.

SlothCreator has extended SwiftUI's Image structure so it's appearing here as an extension. I'll open the Image page and now I can see an initializer that's been added. The documentation for this initializer has the basics right, but it doesn't seem quite up to the same quality as the Sloth structure I looked at earlier. I'd like to improve it. I'll open the Swift file that contains my extension by moving my mouse to the Project navigator and selecting the ImageExtensions file.

And I'll close the Project navigator.

Here's the declaration for the Sloth-based Image initializer.

Directly above the declaration is the symbol's documentation comment, defined by its leading three forward slashes. I'd like to add some additional documentation to this initializer and the best way to write documentation with Xcode 15 is with the new Documentation Preview editor. To activate the Documentation Preview assistant editor, first select the editor options menu.

Then, select the Assistant item. Click on the assistant editor's jump bar to select an assistant mode. Finally, select Documentation Preview. And there it is. Documentation Preview will now remain active as you move between Swift source files, Objective-C header files, and documentation Markdown files. Let's try it out in SlothCreator.

Great. I'll begin by creating a Discussion section. Swift-DocC uses the first line of a documentation comment as the abstract or summary sentence for the page. The next paragraph is used as a Discussion section. I'll write that you... "Use this initializer to display an image representation of a given sloth." As I type, the documentation preview updates in real time, showing me the rendered version of the symbol's documentation. Next, I'd like to add a code example to show how this initializer could be used in practice. I'll begin by creating a code block using Markdown's fenced code block syntax.

I'll specify "swift" as the source language that should be used for syntax highlighting. And I'll paste in my code example.

The example demonstrates how to create a SwiftUI view that renders an image of an ice sloth. And since the example involves UI, I think it would be good to include a screenshot here of what the resulting view would look like. I've already prepared one on my desktop.

But to actually use the screenshot in my documentation, I'll first need to add the image to SlothCreator's documentation catalog. A documentation catalog is a directory of files you can add to your Swift package or Xcode project to provide additional documentation content in the form of Markdown files, images, and videos. This is where you would put longer form articles and tutorials. Any images or videos you add can then be referenced from documentation comments. If I expand the Project navigator, I can see that SlothCreator already has a documentation catalog, so I'll just drag in both the light and dark mode versions of my screenshot.

I can place the images anywhere I like in the documentation catalog and Swift-DocC will find them. This gives me flexibility in how I choose to organize the catalog, structuring it however makes the most sense for me and my team. Then when I want to include an image on a page, I just reference the image by its base file name. It's also important to note that the images and other files included in a documentation catalog are only for documentation. So for example, if you wanted to include an image in your app, you would use an asset catalog. Now I'm ready to add the screenshot to my documentation. I'll use Markdown's image syntax, providing both a description as alt text and the file name of the image. Notice that I've just used the base file name here. DocC will figure out the appropriate light and dark mode versions automatically. I'll finish the documentation with some concluding text.

Nice. The Documentation Preview editor made it straightforward and fun to create expansive documentation for this symbol. Next, I'd like to better organize this method by putting it in a Topic group on the top-level page. I'll activate the Project navigator and select the "SlothCreator" Markdown file in my documentation catalog. The Documentation Preview editor is now showing the rendered content for SlothCreator's top-level page. I really like how I can use the preview editor to better understand how DocC's syntax works. For example, I can see that topic groups are defined by third-level headings underneath a second-level Topics heading. To place a page into a topic group, you create a list item under one of those third-level headings and link to the page. I'll do this now for the extended SwiftUI Image type. Since the Image extension is used to display sloths in a user interface, I think it belongs with the other symbols related to rendering sloths in the Sloth Views topic group. I'll link to it there. Code completion will help me out, by providing a reference to the type.

Great, now the documentation for SlothCreator's Image extension is both well-documented and well-organized. Since we first published the documentation for SlothCreator, we've received feedback asking for a sample code project that demonstrates some of the fundamentals of the framework. To address this, we've put together a small app called Slothy which depends on SlothCreator. My colleague has already put together a rough draft of an article we want to include in SlothCreator's main documentation that links to the new Slothy sample. Let's check it out. I'll begin by adding the article's rough draft to SlothCreator's documentation catalog.

The content here is already really nice. It walks me through the different capabilities of the sample app and even includes screenshots of the app and a link to the repository where folks can download the sample. But I think I can improve it. Fortunately, some new Swift-DocC features make this possible. Swift-DocC's authoring syntax is built on top of Markdown. If you're familiar with Markdown, you should be right at home formatting your content with links, images, bold and italic text, and even tables. Swift-DocC then extends that base Markdown syntax with directives that allow you to take advantage of purpose-built features for your documentation.

I'm going to use of some of these directives now to polish the Slothy sample-code article, but keep in mind that these directives are intended to be used creatively. There isn't one right way to use them or even one right kind of page to use them for. Think about how you could use these directives in your own way to make the documentation for your project easier to follow, more engaging, and more exciting. Before diving in and making edits to the article's layout, I'd like to begin by identifying its concrete problems. That way I can be sure that I'm actually making improvements as I adopt some of these new directives. The first thing that's standing out to me is what's not standing out. This page is styled the same as any other article, despite having sample code that will likely be especially interesting to my reader. And to that point, the most important thing this article is doing, is linking to the source repository for that sample code. Despite that, the sample code link is very difficult to identify and discover. Moving on to the body content of the article. This content is built around two image-paragraph pairs. Each paragraph has an associated image that it's describing. There's two problems here. First, the images are not clearly associated with their paragraphs. And second, the images are taking up far too much room. The images here are intended to accent their respective paragraphs, but they're not very interesting on their own.

Finally, at the bottom of the page is a section describing SlothCreator's localization support. Here there are three different versions of the same screenshot in three different languages. But because they're just stacked vertically, they both lost all association with the localization paragraph and they're just taking up too much room visually. Let's see how we can solve these four problems using Swift-DocC. Let's begin with the article's body content. I think the right solution for the image-paragraph pairs is to place them into a grid. This will better emphasize the importance of the paragraph over the image, and better attach the images to their respective paragraphs. Grids in Swift-DocC are defined as flexible rows and columns. I'll begin by defining a row that contains two columns.

Then I'll place the paragraph in the first column and the image in the second column.

I like how the image is now better attached to its associated paragraph, but I think in this case, the paragraph should take priority over the image. Let's increase the size of the column that contains the paragraph. I can do this by adding a size parameter to the first column and specifying a value greater than the default of one. The size parameter is used to set the span of a given column. I'll try providing a size of three.

My first column is now spanning across three columns in a four column grid. That seems a little too big. How about a size of two? The balance of text and image looks great. Perfect. Let's try the same configuration with the second paragraph-image pair.

This is definitely an improvement, but the page feels a little off-balance now. Let's try flipping the image and paragraph.

Lovely. This article is really coming together now. The problem we identified with the localization section is that the images are taking up too much vertical space, and thus losing context. A tab navigator is the perfect solution here, allowing me to collapse multiple elements into one. Let's try it out.

I'll create the initial structure of a tab navigator with three tabs.

Tab navigators are defined by a containing TabNavigator directive which contains an arbitrary number of child Tab directives. Each tab provides its name as a parameter. I'll place the three images inside their respective tabs.

Now my reader can click through each tab to access the screenshots they're interested in.

To take things just one step further, I'd like to add a quick video that really engages my reader and gets them excited about the sample. Swift-DocC has a video directive for this that I'll insert now.

I'll provide a poster image which will be displayed before the video is played, the video itself, and a description.

Nice. Let's move on to the introduction section. One of the first problems I noticed is how difficult it is to discover the link to access the sample's source code repository. Swift-DocC has a call to action directive that is designed exactly for this. I'll begin by adding a metadata container directive at the top of the page. Metadata directives are used to specify extra information that isn't directly rendered on the page. In this case, I want to attach a call to action to the page.

I've provided a destination URL and purpose to the call to action. Notice that I've used the "link" purpose. Alternatively, I could use "download" if this link led directly to a download, but in this case I'm linking to a source repository, so "link" is the better choice. Finally, I want this article to stand out as different from the rest of the articles in SlothCreator's documentation. I want to be sure reader's don't miss that this page contains sample code. It turns out that Swift-DocC has special support for articles that include sample code. I'll specify that my page kind is sample code by providing a PageKind directive with the "sample code" argument. The rendered page now has a "Sample Code" title heading and a curly-brace page icon to make it stand out as a sample code article. Today, Swift-DocC has just two supported values for the PageKind directive; "article" and "sample code". We'd love to hear about other default page kinds that would be interesting to you, and since Swift-DocC is an open source project, the Swift Forums are a great place to discuss this kind of thing and any other feedback or ideas you might have about how DocC could better meet your documentation needs.

I think developers interested in using SlothCreator in their apps are going to be really excited about this article. It's engaging, thoughtful, and fun. I want to make sure they find it, so let's go back to SlothCreator's top-level page and find a prominent place to link to it.

First, I'll curate the new article into a Topic group. In this case, I think the Essentials group is most appropriate since we expect newcomers to the SlothCreator framework to be interested in the Slothy sample.

This is a good start, but I'd like to take things a step further and feature this article above the page's more generic topic section. The Links directive is perfect for this. I'll create a Featured section and then insert the Links directive.

Links is a great way to highlight pages. You can use it to include a card image and description of a page in a more elevated way. The Links directive accepts a visual style parameter defining the way the link should be rendered and then a list of links in its body, just like a Topic group. I'll link to the Slothy sample.

Links supports a number of visual styles, from a basic list that renders very much like a default topic section, to a detailed grid.

I think the grid style is nice, but I'd like to include a custom image to represent the Slothy sample here. Let's go back to the Markdown for Slothy. To make the Slothy article best prepared for presentation in the grid-based Links section, I need to provide a page image in its metadata. Let's do that now.

I'll specify a purpose of "card" so that this image is used whenever the Slothy article is rendered as a card, and then provide the source of my image and a description as alt text. When I go back to the top-level page for SlothCreator Slothy is now rendered with its custom page image. I'll feature the "Getting Started with Sloths" article as well.

As a finishing touch, I'm going to add some extra metadata to the top-level page as well. I'll start by creating a Metadata directive just like we did before. And then I'll provide a page image.

This time I'm specifying the "icon" purpose instead of "card". So this image will be used anywhere the page's icon is rendered, including in the navigation sidebar and introduction section of the page. Finally, I'm going to set a custom page color.

By default top-level pages use a blue color, but Swift-DocC provides a number of built-in standard colors, like yellow, purple, and orange. SlothCreator generally uses green as its accent color, so I think it would nice to create a more cohesive experience by using it here as well.

Wow. SlothCreator's documentation has come a long way in just a short amount of time. We were able to use layout directives like Row and Column, Tab Navigator, and Video to make this sample code article flow better and engage our reader. We used metadata directives like CallToAction and PageKind to add an extra level of polish. And we tied it all together by elevating featured content with the Links directive, and adding some branding to our top-level page with the PageColor and PageImage directives. I'm really excited to share SlothCreator's updated documentation. But before we publish that new release to the web, let's optimize the online presentation of SlothCreator's documentation with a custom theme.

SlothCreator's documentation is published as part of a larger product website. I want to make sure the documentation site is visually consistent with the product site using the same color palette and set of fonts. Let's take a look at how we can achieve that with custom theming in Swift-DocC. Swift-DocC supports fully customizing the way visual styling like colors, borders, icons, and fonts are rendered on a given deployment of a documentation site. These customizations are done in a special JSON file that you include in your documentation catalog and they allow you to better integrate your documentation site with the rest of your online presence. You might use Swift-DocC's theming tools to match a specific corporate style, or to fit in better with a marketing site or personal blog. However, theming is not the right tool for every documentation customization you might want to make. For example, if you're interested in customizing the look of a specific page, like we did with SlothCreator's sample code page, you should be using a directive on that page instead of a custom theme. Theme customization are site-wide, not page-specific. It's also important to note that Swift-DocC themes are intentionally specific to a deployment. So if you open your documentation in Xcode, your documentation will continue to be rendered with the Xcode theme and look great alongside all the rest of the documentation presented there. This means you can focus your custom theme on your site's web presence without worrying about how it may affect the reading experience in Xcode. But it also means that if you do want a customization to appear both in Xcode and on the web, you're better off using a directive for it. Let's check out SlothCreator's custom theme. Themes in Swift-DocC are defined by a JSON file with the specific name "theme-settings.json" that you place into your project's documentation catalog. There are a number of different kinds of customizations you make with the theme-settings file. For SlothCreator I'm just going to customize the site's colors and fonts. Those customizations are placed in "color" and "typography" sections respectively.

SlothCreator uses a specific shade of green throughout its marketing materials. I already set SlothCreator's top-level-page color to green using the PageColor directive. Now I can set the specific shade of green to be the one I want using the "standard-green" color variable. And because SlothCreator is a pretty serious framework targeting serious sloth professionals, I'd like to use a Serif font in its online documentation. I can do that with the "html-font" typography variable.

Of course, these customizations are just the beginning of what's possible with Swift-DocC theming. I recommend reading Swift-DocC's documentation if you're interested in taking things further. Now that we've configured the "theme-settings.json" file, I'll add it to my documentation catalog.

SlothCreator's source control repository is already configured with continuous integration that uses the "xcodebuild" command-line tool to build and deploy SlothCreator's documentation whenever we push a new commit. This is a great workflow that ensures our documentation is always up-to-date with the latest changes in the framework. If you're interested in setting up a similar workflow for your own project, check out the Swift-DocC section in Xcode's documentation. I'm really excited to publish these changes we put together. Let's commit and push now to trigger a new deployment of the website. I'll move my mouse to the upper left corner of the Xcode window and activate the Source Control navigator. I'll stage all of my changes, add a commit message, commit, and push.

Now I'll open SlothCreator's website. Here's the homepage of SlothCreator's product site. It uses the specific fonts and colors that match SlothCreator's branding. I'll click on the "Read Documentation" button.

And here's SlothCreator's documentation. The website version has the custom theme we applied, with the distinctive font and shade of green. It also has the custom icon we set, and the inviting featured section with the brand-new Slothy sample code article. I'll on the "View sample code" link to open it. I'm really happy with how this article turned out. And of course, Swift-DocC websites continue to come with a great navigation sidebar as well, which makes navigating through the page that I organized in SlothCreator's Topics sections a breeze. At the top is the Essentials group where we placed the Slothy sample code article alongside the "Getting Started" article and the Sloth struct. I'll expand the Sloth struct by clicking the disclosure triangle to its left. This lets me browse the children of the struct, and of course, these symbols are well-organized in topic groups as well. Let's check on the Image initializer we documented earlier. I'll scroll down to the Sloth Views section, expand the Image extension symbol, and click on the initializer. And here we are. I love how the navigation sidebar allows me as a documentation author to create an intuitive browsing experience for developers that really guides them through the API in my project. But sometimes as a documentation reader, I know exactly what page I'm looking for and just need an easy way to jump straight to it. Swift-DocC websites built with Xcode 15 have a brand-new quick navigation feature that makes jumping between pages a snap. Swift-DocC Quick Navigation is another community-driven effort that we're really excited to bring to all Swift-DocC websites. Similar to Xcode's Open Quickly feature, it allows you to jump straight to a page just by activating a keyboard shortcut, and typing its name. Let's try it out. I'll press Shift-Command-O to activate quick navigation.

I can immediately start filtering across all the pages in SlothCreator's documentation. For example, if I'm looking for a getting started article, I might just type "start".

And there it is. I even get a preview of the documentation on the right-hand side.

I'll hit Enter to navigate to the page.

But maybe I need a reminder of what the different sloth powers are. I'll press Shift-Command-O again, and type "power." Here's PowerPicker, and then a "power" property. Ah, here it is, the Power enum. This time I'll on the "View more" link to open the page.

And just like that, I can read about all the available sloth powers. With both the new Quick Navigation popover and the existing Navigation sidebar, Swift-DocC makes browsing through your documentation a really nice experience. Swift-DocC in Xcode 15 comes with powerful new tools for creating truly unique documentation websites. Try out the new Documentation Preview editor. You can have fun exploring different page layouts and knowing how they'll render in real-time. New directives like Row and Column, Links, and PageImage will let you craft documentation that stands out and advocates for your project. And consider if you should add a custom theme to make the web version of your documentation better integrate with your project's branding or existing online presence. To catch up on the latest with Swift-DocC, check out the "What's new in Swift-DocC" session from WWDC22. This session goes in-depth on the new publication workflow that shipped with Xcode 14, showing you exactly how to publish to static hosting services like GitHub pages. And if you're interested in taking your documentation even further with a step-by-step tutorial, I recommend watching "Build interactive tutorials using DocC". I'm so excited to see the documentation you design and publish with Swift-DocC and Xcode 15. Thank you so much. ♪ ♪