Create Documentation for your Swift Playground

Wed, 10 Sep 2014 03:44:16 +0000

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:

[][1]

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:

[][2]

After:

[][3]

Let’s explore.

The Gist

Create yourself a playground (and note where you save it).
Navigate to where the .playground file is saved in Finder.
Right-click the .playground file, and choose “Show Package Contents”.
Add a new folder named “Documentation”.
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…
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).
Open contents.xcplayground with the text editor of your choice by right-clicking and choosing “Open With”.
Modify the XML so that the
element contains a 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 <span class="lang:default decode:true  crayon-inline "><documentation></span> node to the contents.xcplayground file, saved, and voila:  Fancy documentation!

&nbsp;

 [1]: http://www.andrewcbancroft.com/wp-content/uploads/2014/09/Patterns_playground.png
 [2]: http://www.andrewcbancroft.com/wp-content/uploads/2014/09/MyPlayground_WithDocumentation_playground_before.png
 [3]: http://www.andrewcbancroft.com/wp-content/uploads/2014/09/MyPlayground_WithDocumentation_playground_after.png

Documentation on Andrew Bancroft

Create Documentation for your Swift Playground

Before:

After:

The Gist