Sometimes I need to use a third party library (usually added to my project using CocoaPods) so I quickly grab it, integrate it and start adding code. But some frameworks are more difficult to understand, learn and use than others.

Recently I’ve been learning RxSwift. I learn by trying out some code while reading or watching videos. I really need to code for it to stick. I can create a full-blown project and add that RxSwift dependency via CocoaPods, but what I don’t want it’s all the other stuff that comes with a project: storyboards, ViewControllers, etc. I just want to focus on code using pure RxSwift, and take some notes. That’s it.

Playground showing some pages opened with RxCode I won’t describe because I don’t understand yet

Wouldn’t it be perfect if I could create a Markdown document containing RxSwift code that also runs? Well, using Nef the other way around is possible. Nef allows you to create playgrounds that can contain CocoaPods dependencies. Then, you can add text to those Playgrounds using Markdown comments. And finally, Nef allows you to export the contents of this Playground as an standalone Markdown file. It’s documentation that compiles. Nice, isn’t?

Let’s try it! Installation

Let’s go step by step. First thing you need to do is install Nef itself. For that, just type brew install nef in a Terminal. If you don’t have Homebrew installed you can get it from here. It’s a must. Close this and go there. Install brew.

OK, now we have Nef installed. Check you have the latest version typing:

$ nef version

Our first Nef Playground!

We can create a new Nef Playground just typing:

$ nef playground --name HelloWorldPost --platform ios

This will create a project Workspace that contains:

  • a Pod project with all the libraries you want to test / learn about.
  • a project containing you Playground, so you can write code there.

By default Nef always adds the Bow library, a nice library for those into Functional Programming. But in my case I want an empty canvas. So I create my Nef Playgrounds using this command:

$ nef playground --name HelloWorldPost --podfile ./Podfile --platform ios

Here I’m passing in a Podfile with no Pods, so none are installed at the beginning. This is my empty Podfile:

source 'https://github.com/CocoaPods/Specs.git'

platform :ios, '11.0'
use_frameworks!

workspace 'HelloWorldPost.xcworkspace'

Note you have to specify the name of your Workspace. Will be created with that name.

You can also add any pods you want to be installed instead of Bow. For instance to create a Nef Playground with RxSwift you’ll create this Podfile:

platform :ios, '11.0'
use_frameworks!

target 'HelloWorldPost' do

    pod 'RxSwift', '~> 4.0'
    pod 'RxCocoa', '~> 4.0'
end

Writing in the Playground

When Nef has finished, you’ll have a new app in your folder. Open it with open HelloWorldPost.app. Xcode will show your app, and a playground inside.

Xcode showing an empty Playground, and the Pods project created inside our app

Now that you have this new Playground you can write any code you want to try. You can add Markdown comments to the Playground that can be rendered as documentation. Create pages to separate different sections while you’re learning, etc.

Generate your Markdown file

When you’re happy with your code and your prose, you can go ahead and create a Markdown file that can be posted in your blog, printed as PDF, etc. Just use Nef!

$ nef markdown --project HelloWorldPost.app --output markdown

This will output each page in your Playground to the folder markdown. Rendering my Rx Playground I go all this:

🙌 rendered Xcode Playgrounds in 'markdown'
Get playgrounds in 'Rx'... ✓
Get pages in playground 'Rx'... ✓
	• Processing page Observables... ✓
	• Processing page Subscriptions... ✓
	• Processing page Disposing... ✓
	• Processing page Subjects... ✓
	• Processing page Behaviour Subjects... ✓
	• Processing page ReplaySubject... ✓
	• Processing page Variables... ✓
	• Processing page BehaviorRelay... ✓
	• Processing page ignoreElements... ✓
	• Processing page ElementAt... ✓
	• Processing page Filter... ✓
	• Processing page Experiments... ✓
	• Processing page Skip... ✓
	• Processing page Skip Until... ✓
	• Processing page Take... ✓
	• Processing page TakeWhile... ✓
	• Processing page Take Until... ✓
🙌 rendered Xcode Playgrounds in 'markdown'

Uses of Nef

If you’re into blogging, or want to write some docs for your team, or writing a programming book, and really want to be sure those sample code snippets are correct, instead of copying and pasting, correcting, copying and pasting again just use Nef and be always sure everything compiles as it should.

Nef is continuus deployment for your docs.