Create Documentation for your Swift Playground

As I opened Apple’s latest “Patterns Playground” blog post, I was impressed with the look and feel.  Rather than create the documentation as comment blocks, they managed to put in sharp-looking notes and explanations before each code example / experiment.  It’s like an interactive book, reminiscent of the Swift Programming Language iBook!  Here’s a snippet of what their Playground looks like:

Apple's Patterns Playground

Of course, my immediate question / thought was, “How’d they do that?!  Can I do that?  I want to do that!”.  I didn’t know it at the time of this publication, but apparently Apple has some pre-release documentation out on developer.apple.com, detailing how all this is done.  I (as usual) did it the hard way and hacked my way through it.  I figured I’d go ahead and share my discoveries alongside the official documentation from Apple.

I’m already a believer in using Playgrounds for teaching.  The read-example-experiment loop is so easy in the Playground environment.  I think using this documentation technique has the potential to enhance the Playground experience even more to create professional, sharp-looking educational material.  

For this post, I wanted to take a simple example (the File -> New Playground playground) and convert the comment-style documentation into “fancy” documentation.

Before:

Before view of Playground

After:

After view of Playground

Let’s explore.

The Gist

  1. Create yourself a playground (and note where you save it).
  2. Navigate to where the .playground file is saved in Finder.
  3. Right-click the .playground file, and choose “Show Package Contents”.
  4. Add a new folder named “Documentation”.
  5. Create a new HTML file in the Documentation folder.  It should contain the HTML markup and the text explanation that you’d like to enhance your playground with.  Make sure it is a well-formed HTML document by the time you’re finished creating it. I describe a quick way to jumpstart your documentation process at the end of this article…
  6. Although optional, I’d recommend styling your HTML file with appropriate CSS.  Adding a CSS file and referencing it within the HTML file you created is probably a good idea (and this is allowed for Playground documentation).
  7. Open contents.xcplayground with the text editor of your choice by right-clicking and choosing “Open With”.
  8. Modify the XML so that the <sections> element contains a <documentation> node as shown in the highlighted code lines in the example below.  Be sure to replace the relative-path value with the name of the HTML file you created in step 5 (I named mine “doc-fragment-0.html”):
  9.  Save, and open the playground in XCode 6.  Your Playground should now contain documentation!

As a way to jump-start my own Playground documentation, I simply borrowed one of the HTML files and the CSS file from Apple’s Patterns Playground.  Then I modified the markup to contain the educational material I wanted for my playground, customized the styles to what I wanted, added the <documentation> node to the contents.xcplayground file, saved, and voila:  Fancy documentation!