Repository files navigation

nef, short forNefertiti, mother of Ankhesenamun, is a toolset to ease thecreation of documentation in the form of Xcode Playgrounds. It provides compile-timeverification of documentation, exports it inMarkdown format that can be consumed byJekyll to generate websites, and exportCarbon snippets for a given Xcode Playground.

nef is inspired byΛNK for Kotlin andtut for Scala.

💡 Eases the creation of Xcode Playgrounds with support forthird party libraries.

💡Compiles Xcode Playgrounds with support for 3rd-party libraries from the command line.

💡 Builds aPlayground Book for iPad with external dependencies defined in a Swift Package.

💡 GeneratesMarkdown project from nef Playground.

💡 Generates Markdown files that can be consumed fromJekyll to create a microsite.

💡 ExportCarbon code snippets for a given nef Playground.

➜ brew install nef

It will warn you if there is a missing dependency and will provide guidance to install it.

nef can be consumed as a library in yourmacOS project.

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

It is an excellent option if you want to use all nef features in your macOS app, even to build new tooling on top of nef.

You can read more about how to use nef library in thenef site.

Some ofnef features can be used directly in Xcode as an Extension. You can install it directly fromApp Store or downloading the last binary from thereleases section.

You can create Swift Playgrounds -together with third-party libraries- directly in your iPad using the appnef Playgrounds.

You can create anef badge for your GitHub repository, and let users try your project in their iPads.

Xcode Playgrounds are a nice tool for prototyping and trying new concepts. However, third party libraries support is a bit cumbersome to add. One of the goals ofnef is to make the creation of an Xcode Playground easier with support for one or more libraries.

By default,nef can create an Xcode Playground with support forBow, the Functional Programming companion library for Swift.

➜ nef playground

And you can use the following option to specify the name for thenef Playground that you are creating:

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

It will create an Xcode project with support for the latest available version of Bow, namedLatestBowProject in your~/Desktop. If you open thisnef playground, you will find an Xcode Playground where you can import Bow or any of its modules, and start trying some of its features.

By default,nef playground will be created for iOS platform. If you need to change it, you can use the--platform option.

➜ nef playground --platform osx

If you need to take advantage of nef in your Xcode Playgrounds, you can transform your Xcode Playground into a nef Playground using the following command:

➜ nef playground --playground<Xcode Playground>

Where<Xcode Playground> is the path to your Xcode Playground.

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

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

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

target'MyPodsProject'doplatform:osx,'10.14'use_frameworks!pod'Bow','~> 0.3.0'end

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

github"bow-swift/Bow"

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

Xcode lets you check for correctness of your Xcode Playground and run it. However, Apple does not provide us commands to compile an Xcode Playground, as they do for building Xcode projects. It is particularly useful in Continuous Integration when you want to verify that your playgrounds are not broken when the libraries you depend on are updated.nef has an option to compile anef Playground. To do this, you can run the following command:

➜ nef compile --project<nef playground>

If you need to transform your Xcode Playground into a nef Playground you can checkCreating a nef Playground section.

Where<nef playground> is the path tonef Playground where your playgrounds are located. Also, you can use the following option with this command:

• --use-cache: Use cached dependencies if it is possible, in another case, it will download them. Example:

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

You can also clean the result of the compilation:

➜ nef clean --project<nef playground>

Swift Playgrounds is a revolutionary app that makes possible to write Swift code on an iPad. In the latest updates, Swift Playgrounds 3.x has added a new feature:UserModules; it lets you include swift code and make it available across multiple chapters like modules.

nef takes advantage of these new possibilities and advancements in Swift Package Manager to build a Playground Book with external dependencies from a Swift Package specification.

Given aPackage.swift like the next one:

// swift-tools-version:5.2import PackageDescriptionletpackage=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"])])

you can run the following command:

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

It will create a Playground Book (PlaygroundName) with support for the external dependencies and save it in~/Desktop

Options:

• --name: the name for the Playground Book to build.
• --package: path to the Swift Package specification.
• --output: path where the resulting Playground Book will be generated.

Xcode Playgrounds let you write comments in Markdown format using the symbols//: for single line comments, or/*: */ for multiline comments. Inside these comments, you can use any Markdown syntax; an example:

/*: # This is a heading 1 This is regular text. *This is bold text*. [This is a link](http://bow-swift.io). */protocolMyProtocol{}//: ## This is a single line heading 2

It makes Xcode Playgrounds the proper tool to write an article with compilable examples. The command provided bynef to generate the Markdown files is:

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

Options:

• --project: Path to your nef Playground.
• --output: Path where the resulting Markdown project will be generated.

As you can write comments inMarkdown in Xcode Playgrounds, this makes it very suitable to write documentation with compilable examples.Leveraging this,nef can create Markdown files that can be consumed from Jekyll to generate a microsite. The command to do this is:

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

Options:

• --project: Path to your nef Playground.
• --output: Path where the resulting Markdown files will be generated.
• --main-page: Optional. Path to 'README.md' file to be used as the index page of the generated microsite.

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

// nef:begin:hiddenimport Bow // This will be hidden in the Markdown file// nef:endstructPerson{} // This will be present in the Markdown file

Xcode Playgrounds are a great place for prototyping and trying new concepts. Oftentimes we want to share some Swift snippets.Carbon is a cool tool for this, andnef nicely integrates with it. You can take your nef Playground, write several pieces of code, and keep it verified. Later, you can export all your code snippets with the next command:

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

Options:

• --project: Path to your nef Playground.
• --output: Path where the resulting Carbon snippets will be generated.

📣 You can customize the output with the next commands

Command	Description	Format	Options	Default
--background	Background color applied to image	hexadecimal#AABBCC,#AABBCCDD or predefined colors	nefbowwhite greenblueyellow orange	nef
--theme	Carbon's theme to be applied	String	base16-darkblackboardcobaltduotone-darkdraculahopscotchlucariomaterialmonokainight-owlnordoceanic-nextone-darkpanda-syntaxparaiso-darksetishades-of-purplesynthwave-84tomorrow-night-brighttwilightverminalvscodezenburn	dracula
--size	Export file dimensions	Number	[1,5]	2
--font	Font type	String	firaCodehackinconsolataiosevkamonoidanonymousProsourceCodeProdarkMonodroidMonofantasqueMonoibmPlexMonospaceMonoubuntuMono	firaCode
--show-lines	shows/hides number of lines in code snippet	Bool	truefalse	true
--show-watermark	shows/hides watermark in code snippet	Bool	truefalse	true

Example of use

If we have a project created bynef, and an Xcode playground with the next content:

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

Running the following command, we will customize thebackground color to bow,hide the number of lines, and set the export file tosize 3:

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

You can contribute in different ways to makenef better:

• File an issue if you encounter a bug or malfunction innef.
• Suggest a new use case or feature fornef.
• Open a Pull Request fixing a problem or adding new functionality. You can check theIssues to see some of the pending tasks.
• Discuss with us in theGitter channel for Bow about all the above.

Openproject/nef.xcodeproj in Xcode 11 (or newer) and you are ready to go. nef uses the [Swift Package Manager] to handle its dependencies - they will be resolving automatically from Xcode.

• Go to main directory where you can find the nef PlaygroundDocumentation.app.
• Runnef compile --project Documentation.app to set up the project with its dependencies.
• OpenDocumentation.app

For further information, refer to ourContribution guidelines.

Copyright (C) 2019-2021 The nef AuthorsLicensed 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   http://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, softwaredistributed 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 andlimitations under the License.