Introducing nef for Swift projects
by Tomás Ruiz López- •
- April 09, 2019
- •
- swift• functional• bow• nef
- |
- 5 minutes to read.
Earlier this year, we released Bow, a library for typed functional programming in Swift. Since the library’s release, we’ve been working on extensive documentation to ease the use of Bow’s features and make the library more accessible to developers.
An essential part of good documentation is having the content match the current state of the library. For instance, if we add source code to demonstrate specific features of the library, and then later modify the implementation, the examples will likely break. For developers touring new solutions, unusable sample code can be incredibly frustrating and make your library appear unreliable. To avoid this, we’d like to compile the docs we’re writing to verify that everything is in sync with the current state of our library. Enter nef.
nef is a set of command-line tools that let you have compile-time verification of your documentation written as Swift Playgrounds. The inspiration for the library comes from tools like ΛNK for Kotlin and tut for Scala, but nef has been adapted to fit the Swift ecosystem and leverage the existing tools currently available to Swift developers.
nef can be installed using Homebrew and needs Xcode and Cocoapods as dependencies to work. It’s not included in the general repository of brew formulae yet, so you need to tap it first to get the formula to download nef from our repository.
brew tap bow-swift/nef
brew install nef
Now, we’ll explore the main features of nef and how to get the most out of this tool.
Getting a Swift Playground with support for your library
Swift Playgrounds are extremely useful for prototyping new ideas or providing sample code. They also support comments in Markdown format which makes them very suitable for our use case. We can create a Swift Playground with sample code showing how to use Bow, and write the instructions using comments in Markdown.
One drawback with Swift Playgrounds is that support for third-party frameworks can be cumbersome to set up. It usually involves creating an Xcode project that contains the Playground and links to third-party frameworks.
nef eases the creation of such projects using the dependencies you’re including in your Playground. By default, it will create an Xcode project with a Playground that lets you write Swift code with Bow support. This way, you can easily try out the library with minimum set up. You just need to run:
nef playground --name MyProject --version 0.3.0
nef does not stop here; you can provide your own Cocoapods Podfile describing your dependencies and nef will create an Xcode project with a Swift Playground to support them.
Compiling a Swift Playground
Swift Playgrounds can be compiled out-of-the-box in the IDE. However, we need to integrate this into our Continuous Integration process to verify that the docs are not breaking after a change in code. We can also compile Playgrounds from the command line, but with third-party frameworks, they need a little bit of configuration.
nef provides command line compilation of Playground projects created with third-party framework support. It will automatically detect all of the pages in your playground, link them with dependencies, and compile them.
nef compile MyProject
You can also clean the output of the compilation with:
nef clean MyProject
Generating content for Jekyll
Finally, we want to generate a microsite containing the documentation for Bow. Jekyll is a suitable tool for this purpose, as it consumes Markdown files and our Swift Playgrounds are already using this format for comments. Those files need a small amount of reformatting to remove the comment symbols and to enclose the Swift code with the syntax that Markdown uses to highlight code.
nef takes care of this by creating a Markdown file for each page you have in your Swift Playground. Moreover, if you have multiple Swift Playgrounds within your project that contain several pages each, nef will create a section for each of these, group together the pages, and generate a file describing this structure that can be consumed by Jekyll to generate a navigation menu.
nef jekyll MySite --project MyProject
We’ve also added annotations in comments that will let you add metadata for the Jekyll transformation, or, hide certain sections of a Playground page that you don’t want to include in the output file, like imports or utility code. Check out the README file in the repository to review your options.
Conclusion
nef is a lightweight but powerful tool that can help us perform tasks and enhance the process of creating documentation for Bow. We consider high-quality, up-to-date content a crucial component in the success of a library, and nef has been designed to assist us in this endeavor.
During the development of nef, we realized that this could be a useful tool, not just for Bow, but for other projects as well and decided to offer it as a standalone, open source tool. We plan to add additional features as more use cases come to light. In the meantime, please try it out and provide feedback in the Bow Gitter channel
For more information, check out the following Bow and nef resources. Comments and questions are welcome!
Bow and nef are proudly sponsored by 47 Degrees, a Functional Programming consultancy with a focus on the Scala, Kotlin, and Swift Programming languages which supports their active development.