如何制作文档游乐场（混合html和swift代码）？

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?

有没有人想出一个很好的方法来生成一个类似于GuidedTour.playground的文档，其中混合了html部分和swift代码而无需手动执行？

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.

我们可以探索playground文件的内容，它是一个包，它显示了html / swift文件和一个描述结构的contents.xcplayground xml文件，但能够以用户友好的方式创建一个很好。

4 个解决方案

#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)
• Markdown：Jason Sandmeyer的swift-playground-builder可以在GitHub上的https://github.com/jas/swift-playground-builder上找到，可以和npm install -g swift-playground-builder一起安装。也有一个命令行，它也可以通过JavaScript以编程方式调用，因此也可以从Gulp调用（需要Node.JS和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)
• Asciidoc：James Carlson的ad2play可以在GitHub上找到https://github.com/jxxcarlson/ad2play，可以作为Ruby scriipt运行（需要安装Ruby和asciidoctor）

#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.

在Sublime或IDE中打开playground文件夹。您需要在.playground文件夹中编辑.xcplayground扩展文件，因为您在swift代码标记之前或之后插入文档标记。

<?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.

文档和Swift文件和文件夹结构必须是这样的。

#3

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.
• 您可以使用伟大的工作流程自动化工具Grunt（http://gruntjs.com），它经常用于网络行业。
• 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).
• 您可以编写自己的小脚本/应用程序（为什么不在swift本身：D）来解析您的自定义doc文件（使用预定义的语法来标记代码和文档部分）。

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

这两种方式对我来说都是可行的，但问题当然是值得的。

#4

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

从版本6.3开始，此功能现在是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.

通过内联标记注释，内联游乐场结果，查看和编辑游乐场中嵌入的资源的能力以及将辅助源文件集成到Playgrounds的功能，改进了文档创作。这些功能可以在游乐场中创造丰富的新体验。