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

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 2

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.