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

Question

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

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

Answer 1

虽然答案目前标记为＆＃39;正确＆＃39;在撰写本文时可能是真的，实际上有几种方法可以做到这一点。

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

Answer 2

在Sublime或IDE中打开playground文件夹。您需要在.playground文件夹中编辑.xcplayground扩展名文件，以便在swift documentation标记之前或之后插入code标记。

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

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

Answer 3

我非常确定现在没有可用的自动化工作流程（至少没有公共工作流程）。但是，如果你真的需要它，为什么不创造自己的呢？

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

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

Answer 4

从版本6.3开始，此功能现在是Xcode的一部分。

发布说明引用：

  

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