nef，是纳芙蒂蒂 (Nefertiti，阿肯纳顿之妻，图坦卡蒙之母) 的缩写，是一个旨在简化 Xcode Playgrounds 文档创建的工具集。它提供文档的编译时验证，将其导出为 Markdown 格式，供 Jekyll 使用以生成网站，并为给定的 Xcode Playground 导出 Carbon 代码片段。

nef 的灵感来自 Kotlin 的 ΛNK 和 Scala 的 tut。

功能

💡 简化 Xcode Playgrounds 的创建，支持 第三方库。

💡 编译 Xcode Playgrounds，支持从命令行使用第三方库。

💡 构建一个用于 iPad 的 Playground Book，其外部依赖项在 Swift Package 中定义。

💡 从 nef Playground 生成 Markdown 项目。

💡 生成可以被 Jekyll 使用以创建微型网站的 Markdown 文件。

💡 为给定的 nef Playground 导出 Carbon 代码片段。

💻 安装

📟 使用 Homebrew (首选)

➜ brew install nef

如果缺少依赖项，它会发出警告，并提供安装指南。

📦 使用 Swift Package Manager

nef 可以作为库在您的 macOS 项目中使用。

.package(url: "https://github.com/bow-swift/nef.git", from: "{version}")

如果您想在您的 macOS 应用程序中使用所有 nef 功能，甚至在 nef 之上构建新的工具，这是一个绝佳的选择。

您可以在 nef 网站上阅读更多关于如何使用 nef 库的信息。

🔌 使用 Xcode 编辑器扩展

nef 的一些功能可以直接在 Xcode 中作为扩展使用。您可以直接从 App Store 安装，或从 发布部分下载最新的二进制文件。

📲 使用您的 iPad

您可以使用应用程序 nef Playgrounds 在您的 iPad 上直接创建 Swift Playgrounds (包括第三方库)。

使用 GitHub 徽章

您可以为您的 GitHub 存储库创建一个 nef 徽章，让用户可以在他们的 iPad 上尝试您的项目。

用法

📃 创建 nef Playground

Xcode Playgrounds 是原型设计和尝试新概念的好工具。然而，第三方库的支持添加起来有点麻烦。 nef 的目标之一是使创建 Xcode Playground 更容易，并支持一个或多个库。

默认情况下，nef 可以创建一个支持 Bow (Swift 的函数式编程辅助库) 的 Xcode Playground。

➜ nef playground

您可以使用以下选项来指定您正在创建的 nef Playground 的名称

➜ nef playground --output ~/Desktop --name LatestBowProject

它将在您的 ~/Desktop 中创建一个支持最新可用版本的 Bow 的 Xcode 项目，名为 LatestBowProject。如果您打开这个 nef playground，您会发现一个 Xcode Playground，您可以在其中导入 Bow 或其任何模块，并开始尝试其一些功能。

默认情况下，将为 iOS 平台创建 nef playground。如果您需要更改它，可以使用 --platform 选项。

➜ nef playground --platform osx

如果您需要在 Xcode Playgrounds 中利用 nef，您可以使用以下命令将您的 Xcode Playground 转换为 nef Playground

➜ nef playground --playground <Xcode Playground>

其中 <Xcode Playground> 是您的 Xcode Playground 的路径。

📣 您可以创建一个与任何不同 Bow 版本、分支或提交兼容的 nef Playground；甚至支持第三方依赖项

注意：以下选项是互斥的。

--bow-version <x.y.z>：指定您想在项目中使用的 Bow 的版本。此选项允许您在 Xcode Playground 中测试该库的旧版本。示例

➜ nef playground --name OldBowProject --bow-version 0.3.0

--bow-branch <branch name>：指定您想在项目中使用的 Bow 的分支。此选项允许您测试 Bow 的仍在开发中的分支中的功能，该分支尚未合并或发布。示例

➜ nef playground --name BranchBowProject --bow-branch master

--bow-commit <commit hash>：指定您想在项目中使用的 Bow 的提交哈希值。此选项允许您在需要时准确地测试 Bow 的功能，无论是否发布。示例

➜ nef playground --name CommitBowProject --bow-commit e70c739067be1f5700f8b692523e1bb8931c7236

--podfile <podfile>：指定一个包含您自己依赖项的 Podfile。此选项允许您创建一个支持其他库的 Playground。创建一个列出您的依赖项的 Podfile，并将其传递给 nef。示例

您的 Podfile，位于 ./folder/dependencies

target 'MyPodsProject' do
  platform :osx, '10.14'
  use_frameworks!

  pod 'Bow', '~> 0.3.0'
end

➜ nef playground --name MyPodsProject --podfile ./folder/dependencies/Podfile

--cartfile <cartfile>：指定一个包含您的依赖项的 Cartfile。创建一个列出您的依赖项的 Cartfile，并将其传递给 nef。示例

您的 Cartfile，位于 ./folder/dependencies

github "bow-swift/Bow"

➜ nef playground --name MyCarthageProject --cartfile ./folder/dependencies/Cartfile

🔨 编译 nef Playground

Xcode 允许您检查 Xcode Playground 的正确性并运行它。但是，Apple 没有为我们提供编译 Xcode Playground 的命令，就像构建 Xcode 项目一样。当您想验证您依赖的库更新时，您的 Playground 没有损坏时，这在持续集成中特别有用。 nef 有一个编译 nef Playground 的选项。为此，您可以运行以下命令

➜ nef compile --project <nef playground>

如果您需要将您的 Xcode Playground 转换为 nef Playground，您可以查看创建 nef Playground 部分。

其中 <nef playground> 是您的 Playground 所在的 nef Playground 的路径。此外，您可以使用以下选项与此命令一起使用

--use-cache：如果可能，使用缓存的依赖项，否则，将下载它们。示例

➜ nef compile --project <nef playground> --use-cache

您还可以清理编译结果

➜ nef clean --project <nef playground>

📲 创建 Playground Book

Swift Playgrounds 是一款革命性的应用程序，可以在 iPad 上编写 Swift 代码。在最新的更新中，Swift Playgrounds 3.x 添加了一个新功能：UserModules；它允许您包含 Swift 代码，并使其像模块一样在多个章节中可用。

nef 利用 Swift Package Manager 中的这些新可能性和改进，构建一个 Playground Book，其中包含来自 Swift Package 规范的外部依赖项。

给定一个像下面这样的 Package.swift

// swift-tools-version:5.2

import PackageDescription

let package = Package(
    name: "BowProject",
    products: [
        .library(name: "BowProject", targets: ["nef"])
    ],
    dependencies: [
        .package(url: "https://github.com/bow-swift/bow.git", from: "0.8.0"),
    ],
    targets: [
        .target(name: "nef", dependencies: ["Bow"])
    ]
)

您可以运行以下命令

➜ nef ipad --name PlaygroundName --package Package.swift --output ~/Desktop

它将创建一个支持外部依赖项的 Playground Book (PlaygroundName)，并将其保存在 ~/Desktop 中

选项

--name：要构建的 Playground Book 的名称。
--package：Swift Package 规范的路径。
--output：将生成结果 Playground Book 的路径。

🔖 生成 Markdown 项目

Xcode Playgrounds 允许您使用符号 //: 用于单行注释，或 /*: */ 用于多行注释，以 Markdown 格式编写注释。在这些注释中，您可以使用任何 Markdown 语法；一个例子

/*:
 # This is a heading 1

 This is regular text. *This is bold text*. [This is a link](http://bow-swift.io).
 */
protocol MyProtocol {}

//: ## This is a single line heading 2

这使得 Xcode Playgrounds 成为编写带有可编译示例的文章的适当工具。由 nef 提供的生成 Markdown 文件的命令是

➜ nef markdown --project <nef playground> --output <path>

选项

--project：您的 nef Playground 的路径。
--output：将生成结果 Markdown 项目的路径。

🌐 为 Jekyll 生成 Markdown 文件

由于您可以在 Xcode Playgrounds 中以 Markdown 格式编写注释，这使得它非常适合编写带有可编译示例的文档。利用这一点，nef 可以创建可以被 Jekyll 使用以生成微型网站的 Markdown 文件。执行此操作的命令是

➜ nef jekyll --project <nef playground> --output <path> --main-page <main-page>

选项

--project：您的 nef Playground 的路径。
--output：将生成结果 Markdown 文件的路径。
--main-page：可选。要用作生成的微型网站的索引页面的 'README.md' 文件的路径。

📣 如何为 Jekyll 设置 nef Playgroud？

nef 查找 nef Playground 中的所有 Xcode Playgrounds。每个 Playground 都被认为是生成的微型网站结构中的一个部分。对于 Playground 中的每个页面，都会在相应的部分中创建一个条目。该页面使用上述语法从 Swift 转换为 Markdown。结果，生成与 nef Playground 结构匹配的目录结构，以及可以用作 Jekyll 中的菜单的 sidebar.yml。

nef 添加了一些命令来修改 Markdown 转换过程。所有 nef 命令都包含为 Swift 注释。它们以 // nef:begin: 开头，以 // nef:end 结尾。支持的命令有

header：它允许您向 Playground 页面添加元数据，以供 Jekyll 使用。您必须提供此页面将在 Jekyll 中使用的布局。其余属性是可选的，您可以根据您的 Jekyll 配置包含其中的任何一个。 nef 也会处理永久链接。示例 (在 Playground 页面的开头)

// nef:begin:header
/*
  layout: docs
*/
// nef:end

hidden：它允许您在输出的 Markdown 文件中隐藏 Playground 的一部分。这对于隐藏导入或支持实用程序代码以使示例工作很有用。示例

// nef:begin:hidden
import Bow // This will be hidden in the Markdown file
// nef:end

struct Person {} // This will be present in the Markdown file

🌁 导出 Carbon 代码片段

Xcode Playgrounds 是原型设计和尝试新概念的好地方。通常我们想分享一些 Swift 代码片段。 Carbon 是一个很酷的工具，nef 与它很好地集成。您可以使用您的 nef Playground，编写几段代码，并保持其验证。稍后，您可以使用以下命令导出您的所有代码片段

➜ nef carbon --project <nef playground> --output <path>

选项

--project：您的 nef Playground 的路径。
--output：将生成结果 Carbon 代码片段的路径。

📣 您可以使用以下命令自定义输出

命令	描述	格式	选项	默认
`--background`	应用于图像的背景颜色	十六进制 `#AABBCC`, `#AABBCCDD` 或预定义的颜色	`nef` `bow` `white` `green` `blue` `yellow` `orange`	`nef`
`--theme`	要应用的 Carbon 主题	字符串	`base16-dark` `blackboard` `cobalt` `duotone-dark` `dracula` `hopscotch` `lucario` `material` `monokai` `night-owl` `nord` `oceanic-next` `one-dark` `panda-syntax` `paraiso-dark` `seti` `shades-of-purple` `synthwave-84` `tomorrow-night-bright` `twilight` `verminal` `vscode` `zenburn`	`dracula`
`--size`	导出文件尺寸	数字	[`1`, `5`]	`2`
`--font`	字体类型	字符串	`firaCode` `hack` `inconsolata` `iosevka` `monoid` `anonymousPro` `sourceCodePro` `darkMono` `droidMono` `fantasqueMono` `ibmPlexMono` `spaceMono` `ubuntuMono`	`firaCode`
`--show-lines`	显示/隐藏代码片段中的行号	布尔值	`true` `false`	`true`
`--show-watermark`	显示/隐藏代码片段中的水印	布尔值	`true` `false`	`true`

使用示例

如果我们有一个由 nef 创建的项目，以及一个包含以下内容的 Xcode playground

let example = "This is an example"
print("nef is super cool: \(example)")

// nef is super cool: This is an example

运行以下命令，我们将 background color 自定义为 bow，隐藏行号，并将导出文件设置为 size 3

➜ nef carbon --project . --output ~/Desktop/nef-carbon --background bow --size 3 --show-lines false

❤️ 为项目做贡献

您可以通过不同的方式为改进 nef 做贡献

如果您在 nef 中遇到 bug 或故障，请提交 issue。
为 nef 提出新的用例或功能。
打开一个 Pull Request 来修复问题或添加新功能。您可以查看 Issues 来查看一些待处理的任务。
在 Bow 的 Gitter 频道中与我们讨论上述所有内容。

如何运行项目

在 Xcode 11（或更高版本）中打开 project/nef.xcodeproj，您就可以开始了。 nef 使用 [Swift Package Manager] 来处理其依赖项 - 它们将从 Xcode 自动解析。

如何运行文档项目

转到主目录，您可以在其中找到 nef Playground Documentation.app。
运行 nef compile --project Documentation.app 以使用其依赖项设置项目。
打开 Documentation.app

有关更多信息，请参阅我们的贡献指南。

⚖️ 许可证

Copyright (C) 2019-2021 The nef Authors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   https://apache.ac.cn/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.