How to create a playground for documentation (mixing html and fast code)?

Question

Has anyone come up with a good way to create a document similar to GuidedTour.playground, with a combination of html sections and quick code without having to do it manually?

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

Answer 1

Starting with version 6.3, this function is now part of Xcode.

Quote from the release note:

Improved documentation with built-in comments, built-in results of playgrounds, the ability to view and edit resources built into playgrounds, and the ability to integrate auxiliary source files into playgrounds. These features allow you to create rich new experiences on the playgrounds.

Answer 2

Although the answer that is currently marked as “correct” may be true at the time of writing, there are actually several ways to do this.

• Markdown: Jason Sandmeyer swift-playground-builder is available on GitHub at https://github.com/jas/swift-playground-builder and can be installed using npm install -g swift-playground-builder . In addition, it has a command line, it can also be programmed from JavaScript and, therefore, called from Gulp (requires Node.JS and NPM)
• Asciidoc: James Carlson ad2play is available on GitHub at https://github.com/jxxcarlson/ad2play and can work as a ruby ​​scriipt (requires Ruby and asciidoctor installed)

Answer 3

Open the playground folder in Sublime or IDE. You need to edit the .xcplayground extension file in this .playground folder, where you insert the documentation tag right before or after the 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 structure of Swift files and folders should be like this.

Answer 4

I am sure that at the moment there is no automated workflow (at least there is no public). But why not create your own if you really need one?

• You can use the tool the great Grunt workflow automation tool ( http://gruntjs.com ), which is pretty often used in the web industry.
• You can write your own small script / app (why not the fastest: D) ​​to parse your own doc file (with predefined syntax for marking sections of code and documentation).

Both methods may be applicable to me, but the question is certainly worth it if it is worth it.