How to produce a documentation playground (mixing html and swift code)?

Question

Has anyone figured out a nice way to produce a document similar to the GuidedTour.playground with a mix of html sections and swift code without having to do it manually?

We can explore the content of the playground file which is a package and it shows html/swift files and a contents.xcplayground xml file describing the structure but it would be nice to be able to create one in a user-friendly way.

Answer 1

As of version 6.3 this feature is now part of Xcode.

Quote from the release note:

Improved documentation authoring with inline marked-up comments, inline playground results, the ability to view and edit resources embedded in playgrounds, and the ability to integrate auxiliary source files into Playgrounds. These features enable the creation of rich new experiences in playgrounds.

Answer 2

Although the answer currently marked as 'correct' may have been true at the time of writing, there are in fact several ways to do this.

• Markdown: Jason Sandmeyer's swift-playground-builder is available on GitHub at https://github.com/jas/swift-playground-builder and can be installed with npm install -g swift-playground-builder. As well has having a command line it can also be programmatically invoked from JavaScript and therefore called from Gulp as well (requires Node.JS and NPM)
• Asciidoc: James Carlson's ad2play is available on GitHub at https://github.com/jxxcarlson/ad2play and can be run as a Ruby scriipt (requires Ruby and asciidoctor installed)

Answer 3

Open the playground folder in Sublime or an IDE. You need to edit the .xcplayground extension file within that .playground folder as such where you insert documentation tag right before or after swift code tag.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<playground version='3.0' sdk='macosx'>
    <sections>
        <code source-file-name='section-1.swift' hidden="true" />
        <documentation relative-path='fragment0.html'/>
        <code source-file-name='section-3.swift'/>
        <documentation relative-path='fragment11.html'/>
        <code source-file-name='section-5.swift'/>
        <documentation relative-path='fragment21.html'/>
        <code source-file-name='section-7.swift'/>
        <documentation relative-path='fragment22.html'/>
        <code source-file-name='section-9.swift'/>
        <documentation relative-path='fragment23.html'/>
        <code source-file-name='section-11.swift'/>
        <documentation relative-path='fragment24.html'/>
        <code source-file-name='section-13.swift'/>
        <documentation relative-path='fragment25.html'/>
        <code source-file-name='section-15.swift'/>
        <documentation relative-path='fragment26.html'/>
        <code source-file-name='section-17.swift'/>
        <documentation relative-path='fragment27.html'/>
        <code source-file-name='section-19.swift'/>
        <documentation relative-path='fragment31.html'/>
        <code source-file-name='section-21.swift'/>
        <documentation relative-path='fragment32.html'/>
        <code source-file-name='section-23.swift'/>
        <documentation relative-path='fragment33.html'/>
    </sections>
    <timeline fileName='timeline.xctimeline'/>
</playground>

The documentation and Swift file and folder structure need to be like this.

Answer 4

I am pretty sure there is no automated workflow (at least no public one) available for now. But why don't create your own if you really need it?

• You can use the great workflow-automation tool Grunt (http://gruntjs.com) which is quite often used in the web-industry.
• You can write your own little script/app (why not in swift itself :D) to parse your custom doc-file (with a predefined syntax to mark code- and documentation sections).

Both ways seam feasible to me, but the question is of course if it is worth it.