bow-swift/nef

💊 steroids for Xcode Playgrounds

nef's Issues

Refactor bash scripts to Swift-FP using Bow

To reduce the legacy code and make it more stable, we need to migrate the whole bash-scripts to Swift in purely functional programming.

We need to migrate the next scripts:

• nef (presenting menus + version option) (close: #127) [tracked in #126 , #129]
• nef-clean (clean up nef Playground) [tracked in #128]
• nef-playground [fix bug: #121] [tracked in #125]
• nefc (compiler) [fix bug: #122] [tracked in #124]
• nef-carbon [tracked in #118]
• nef-jekyll [tracked in #113, #117]
• nef-markdown [tracked in #108, #115]
• nef-jekyll-page [tracked in #107, #113]
• nef-markdown-page [tracked in #107, #108]
• nef-common [tracked in #109, #110]

After the refactor, we will find the whole code in the Xcode project nef > project > nef.xcodeproj and it will be divided into 4 layers:

• UI it'll contain the new CLI swift-FP scripts.
• Component the whole frameworks under the nef umbrella. It will provide the entire business-logic for nef and let to devs import in their projects, to use the API directly.
• Core to parser/create/render AST from Xcode Playgrounds. It interprets the raw Xcode Playground page.
• Tests when the whole code will be in Swift, it will be accessible to testing and reduce the regression between each release.

Microsite for nef

We will implement Jekyll site to Nef library

Add verbose mode to command-line

Description

It will be fine run nef using verbose mode, so you do not need to access to log system. Sometimes, for example if you run nef in CI, you do not have access to the filesystem so we think it is a need option.

Example of use

→ nef playground --verbose

Export to Carbon

Description

Add a rendering mode to export pages of a playground, or sections from them, to images with Carbon. For sections, this is the suggested syntax:

// nef:begin:carbon
enum Result<E, A> {
  case success(A)
  case failure(E)
}
// nef:end

Parameters

Carbon supports the following query parameters to customize the output:

• Background color: bg=rgba([r]%C[g]%C[b]%C[a]) where [r], [g] and [b] take integer values from 0 to 255, and [a] take floating point values from 0 (fully transparent) to 1.
• Theme: coloring theme for the image. t=[theme] where [theme] can be one of the following values: 3024-night, blackboard, base16-dark, base16-light, cobalt, dracula, duotone-dark, hopscotch, lucario, material, monokai, night-owl, nord, oceanic-next, one-light, one-dark, panda-syntax, paraiso-dark, seti, shades-of-purple, solarized%20dark, solarized%20light, tomorrow-night-bright, twilight, verminal, yeti, zenburn.
• Window theme: style of the window. wt=[theme] where [theme] can be one of the following values: none, sharp, bw.
• Language: l=swift for all our purposes.
• Vertical and horizontal padding: pv=[padding]px and ph=[padding]px where [padding] is a positive integer.
• Drop shadow: ds=true or false.
• Shadow y-offset: dsyoff=[y]px where [y] is a positive integer number.
• Shadow blur: dsblur=[x]px where [x] is a positive integer number.
• Window controls: wc=true or false.
• Line numbers: ln=true or false.
• Auto adjust width: wa=true or false.
• Carbon watermark: wm=true or false.
• Font: fm=[font] where [font] is one of the available fonts (suggested: Fira%20Code).
• Font size: fs=[size]px where [size] is a positive integer number.
• Line height: lh=[percentage]%25 where [percentage] is a positive integer number (greater than 100 for correct visualization, default to 133).
• Export size: es=[x] where [x] can be one of 1x, 2x or 4x.

Behavior

Opening a URL with the parameters above should give us the chance to visualize the code between the nef annotations with the aspect we customized. We need to explore if the image can be extracted automatically and saved to a specific path, allowing us to perform batches of operations generating multiple images.

Render Slides compatible with Reveal

Description

nef is giving superpowers to Swift Playgrounds; a good feature will be to create slides from Playgrounds. A good option will be to add compatibility to Reveal - so you can custom your templates, transitions... and connect two powerful tools.

We are thinking about to remove node dependency, so using nef it will render your Swift Playground into a final HTML file compatible with Reveal.

nef --version

Don't know how to check Nef's version number. Tried nef -v, nef -version, nef --version to no avail.

Ideally nef --version should return that build's version number

Export to Carbon: carbon's render

We need to update the Markdown library to add Carbon render. Receiving a playground page library will export each Node.Code as Carbon snippet

Creating and compiling default Playground works but inform that "fails" in macOS 10.14

I'm in macOS 10.14.6. Don't ask coughAppceleratorcough

To replicate:

$ nef playground --name test                                   
Installing Playground (test)... ✅
Set test target to iOS ✅
Updating version (0.7.0)... ✅
Installing Pods ... ✅
$ nef compile test.app              
Installing Pods ... ✅
Building test (test) ... ✅
Copy frameworks ✅
Found 1 playgrounds
   Compiling page.xcplaygroundpage ...<unknown>:0: error: Swift does not support the SDK 'MacOSX10.14.sdk'

If you open test.app and compile, all is OK.

So although we get that error message, seems like it's compiling OK and also can generate markdown fine.

nef Jekyll documentation

Export to Carbon: parametrize cli

Using the parametrized carbon's script nef-carbon-page done in this PR #57. In this issue, we will connect to nef to expose this functionality from CLI:

Example of use

nef carbon --project . --output ~/Desktop <params optionals>

where <params optionals> are:
--background - this is the background color
--theme
--size - export file size
--font - font type
--lines - show/or not the lines in the exported code snippet.
--watermark - show/or not the watermark in the exported code snippet.

Compiler with dependencies in `nefc` from Swift 5.01

It looks to me that static linking doesn't work on Linux nor macOS any longer. According to SR-9946 "Swift on macOS isn't going to support static linking at all", and static linking is disabled for Linux in SPM.

Bug in permalinks - Jekyll

When writing permalinks for Jekyll is better to always write them ending at / slash. That way the files/path generated in the end could be navigated through <your-site>/<permalink> and <your-site>/<permalink>/. Without it, a path not ending in a slash will give you a 404

Export to Carbon: bash script

Using carbon's render (review issue #56) - connect it to nef set tool script. Automate the task to find the whole playgrounds (in a project), get the whole page inside each playground and export the code snippets for each page.

nef ⚉- Xcode Playgrounds ⚉- Pages ⚉- Page ⚉- Node.Code <--> Carbon Snippet

Populate microsite

Add description and examples of use for the microsite.

What should be documented?

• (verification) How to compile from the command line a Swift Playground project.
• (documentation) How to convert an ordinary playground to a nef Playground
• (documentation) How to start an Xcode Playground with 3rd-party libraries compatibility.
• (documentation) How to start a Swift Playground (iPad) with 3rd-party libraries compatibility.
• (render) How to build a Markdown project from nef Playground.
• (render) How to build a Jekyll site from nef Playground.
• (render) How to render Carbon images from nef Playground.
• (General) What is the FP architecture has nef. I think it will be useful for landing new contributors to nef project.
• (General) How to use the API nef, for building new projects/tooling on top of nef.
• (General) What is the nef Xcode extension and How to use it :)

Nef logo

We will create a logo for the nefproject.

Nef fails to generate Playground if path contains spaces

Steps to reproduce

• cd; cd Desktop
• mkdir "test spaces"
• cd test\ spaces
• nef playground --name test

You get these errors:

Installing Playground (test)...mv: rename /Users/dfreniche/Desktop/nef/test to /Users/dfreniche/Desktop/nef/test spaces/test.app/Contents/MacOS/test: No such file or directory
mv: rename spaces/test.app.1/* to /Users/dfreniche/Desktop/nef/test spaces/test.app/Contents/MacOS/*: No such file or directory

and

Installing Playground (test)...mv: rename /Users/dfreniche/Desktop/nef/test to /Users/dfreniche/Desktop/nef/test spaces/test.app/Contents/MacOS/test: No such file or directory
mv: rename spaces/test.app.1/* to /Users/dfreniche/Desktop/nef/test spaces/test.app/Contents/MacOS/*: No such file or directory

GitHub Action to compile Xcode Playground

We want to publish a GitHub action to let users compile its Xcode Playgrounds (no external dependencies)

Run playgrounds and check whether they throw uncaught exceptions

If I run swift MyPlayground.playground/Contents.swift where MyPlayground is a simple playground with just this content:

struct E: Error {}
throw E()

I can tell that the playground raised an uncaught exception by inspecting the exit code of the command.

I guess the same idea can be adapted to the playgrounds nef generates.

This would be useful because I could add XCTest assertions on my playground and nef would check for me that they all pass (just like python's doctest)

For simple projects it's useful to just have the documentation be also the unit tests.

Maybe this behavior can be guarded with a new command-line argument.

nef jekyll --watch

I usually write my docs on a swift playground while previewing the generated jekyll site in my browser.

I use jekyll serve, but I still to run nef jekyll manually in order for the generated markdown to be updated on a change.

I'd love a --watch option so nef automatically regenerates the markdown files for me.

Docs site nested entries support

We need to allow the docs website sidebar to show nested options under some entries.

Currently only one level is supported.

GitHub Action to compile/verify nef Playground

We want to publish a GitHub action to let users compile its nef Playgrounds (with 3rd-party libraries)

Add autocompletation to terminal

nef has a lot of commands and options I think is the time to integrate an autocompletion in the installer. So your terminal helps you to choose between all the options.

It should be nice if this autocompletion works on:

• bash
• zsh

Update `nef` README with the last changes

Before to publish the versión 0.2.0 we need to update the README

List Bow's pods and allow selection

Custom background for microsite

Allow changing the background color from headers section in md files.

example of use

----------------
 layout: docs
 background: #FFFFFF
----------------

Swift Package Manager support

Thanks for the awesome tool!
It would be great to have SPM support!

Export to Carbon: update documentation

After Carbon integration we will need to update the documentation:

• Update the README for adding how use nef carbon from CLI (tracked in #73)
• Update the microsite Integration section to add information about how to use Carbon and what it is. (tracked in #74 )

nefc should be less verbose

nefc should be less verbose in output.

NEFC has 3 steps of compilation:

1. build external dependencies using cocoapods
2. build project
3. build playgrounds pages

Step 3 is console user-friendly and generate logs with the outputs - in steps 1 and 2 nef should do the same

`nef` testing

Description

Add testing support to nef to reduce the boilerplate for using XCTests (or any third party library).

Example of use

we could add to our Swift Playground something like:

import XCTest

class ExampleTests: XCTestCase {

    func testHelloWorld_Success() {
        let helloWorld = "Hello World!"
        XCTAssertEqual(helloWorld, "Hello World!")
    }

    func testHelloWorld_Failure() {
        let helloWorld = "Hello World!"
        XCTAssertEqual(helloWorld, "Hello World! - Failure")
    }
}

and launch this TestCase using nef as follow:

Nef.run(testCase: ExampleTests.self)

in this example, the output will be:

As you can see, test failures and final state for test suit is remarked.

Bug delete project folder

Description

If the project name input is the same as the playground page, then jekyll, carbon, markdown remove the project folder and fails.

Proposal

Detect when these kinds of coincidences are given and abort CLI with a descriptive error.

Generate microsite using Swift Playgrounds

Could not extract any module from packages

I have a problem building playground book.

Here is the Package.swift file.

// swift-tools-version:5.1
// The swift-tools-version declares the minimum version of Swift required to build this package.
import PackageDescription

let package = Package(
    name: "Table",
    products: [
        // Products define the executables and libraries produced by a package, and make them visible to other packages.
        .library(
            name: "Table",
            targets: ["Table"]),
    ],
    dependencies: [
        // Dependencies declare other packages that this package depends on.
        // .package(url: /* package url */, from: "1.0.0"),
    ],
    targets: [
        // Targets are the basic building blocks of a package. A target can define a module or a test suite.
        // Targets can depend on other targets in this package, and on products in packages which this package depends on.
        .target(
            name: "Table",
            dependencies: []),
        .testTarget(
            name: "TableTests",
            dependencies: ["Table"]),
    ]
)

Get modules from repositories...... ✗
	| could not extract any module from packages
	|
☠️ rendering Playground Book. Swift Playground generator failure.
```console

Export to Carbon: parametrize

Parametrize the carbon's query for customizing the code snippet. Here you can find a list of parameters we can extract to flags for nef - in this issue we will work on carbon core - lib dependency: nef-carbon-page

Verbose log for jekyll

Log for nef-jekyll is only if it works or not. We want to show what happens during the render and in case something fails, show the AST with the invalid node.

Bug in `xcproject` - new pages for playgrounds

Description

Sometimes, if you copy-paste, an existing playground in an existing nef project, the logic tree for Xcode project gets absolute paths instead of relative.

While Apple fixes it in Playgrounds - we should take it in mind for generators (jekyll, markdown, carbon...)

Example

if I have a nef project BugTesting, and I link an external playground (ex. Playground.playground) - this should be linked like relative path ./Playground.playground - but if we explore logic tree we will read /User/<username>/BugTesting/Playground.playground (it is a wrong Apple behaviour)

Render PDF

Description

it should be super cool if we could render Swift Playgrounds to PDF files.

Carthage support

In order to integrate the most important dependency managers in nef, we will add support to Carthage.

• Break CocoaPods dependency to install nef and build template. (tracked in #88)
• nef compiler add Carthage supports to compiler | clean | dependencies options. (tracked in #90)
• nef playground should be compatible with third-party libraries using Carthage - add --carthage flag (tracked in #91)
• Update README to include this new flag in nef playground + information about Carthage supports

nef modularization - open API

Description

We want to open nef to developers. On this way, nef should be easily imported into Xcode projects to expand its power.

Goal

Then we could take advantage of these renders in any other external Xcode project.

Proposal

We want to modularize nef - so internal Core does not depend on CLI. We need to extract the whole renders and isolate in a Cored module; moreover, we need to create a Component framework to open API to developers so they can use the main nef's features:

• Generate Jekyll microsite.
• Generates Markdown files.
• Export Carbon snippets from code selection.

How will it be developed?

nef project should be modularized as follow:

• UI: module with the CLI dependencies
• Componentes: public modules to be imported in your macOS project. It is the open API to nef.
• Core: private modules where analysis syntax, lexical and rendered will happen.

Roadmap

• Modularize nef (tracked in #80)
• Open API for Carbon (tracked in #80)
• Open API for Jekyll (tracked in #82)
• Open API for Markdonw (tracked in #81)

["Bug"] nef compile Could not get playgrounds at path

Description

I run nef compile and I got an error on a playground that previously worked fine

nef compile --project SensorDocs.app/

Expected outcome

The playground is built.

Observed outcome

I get the following error:

Getting playgrounds in MacOS ✗
☠️ compiling Xcode Playgrounds from '[...]SensorDocs.app' failed with error:
Compiler failure. Could not get playgrounds at '[...]SensorDocs.app/Contents/MacOS'

nef modules, version, platform

macOS playground
nef 0.6.1

Tooling

• Xcode version: 11.5

Other

Same issue with the markdown command

Maybe it's a permissions problem? Maybe something wrong with some path?
Let me know how can I help debugging this.

nef-doc

Script to generate documentation from playground page - compatible with Jekyll

Error on "Installing Pods" step

→ nef playground --platform osx
Installing Playground (BowPlayground)... ✅
Set BowPlayground target to macOS ✅
Updating version (0.7.0)... ✅
Installing Pods ... ❌
error: pod install review 'nef/log/pod-install.log' for more information.

nef/log/pod-install.log doesn't exist in the current directory so there's no way for me to check logs.

Relatives url in submenus

We should set inner nested urls as relative as higher level ones in the docs sidebar menu.

nef-playground

Build a basic playground with support to Bow

Skip installing pods step

During setup on CI there is a step to install pods so it's redundant. It would be nice to have an option to skip this step :)

Add banner with Logo in Readme

Allow `nef` compiler change dependencies

Description

nefc should allow changing on the fly the dependencies. For example, the CI needs to set the dependencies to the current branch for verifying the written documentation continues working.

Remove CocoaPods dependency from playground install

In nef playground command, it is installing a playground using the command pod lib create from CocoaPods.

In our path, we want to remove any dependency to Cocoapods to integrate other dependency managers (Carthage | SPM) and do not force the users to install any others.

["Bug"] Cannot compile playground with a /* */ comment

Description

I have a playground page that compiles normally. When adding a /* Comment */ and running nef compile I get a Syntax analysis failed error.

Expected outcome

I can compile the playground, it's just code and comments.

Observed outcome

I get the following error:

Getting playgrounds in MacOS ✓
Getting pages in playground MyPlayground ✓
	• Processing page 1. Introduction ✗
☠️ compiling Xcode Playgrounds from '[...]MyPlayground.app' failed with error:
Compiler failure. Cannot render content: Syntax analysis failed. Possible issues:
	- File is empty
	- Check all the begin/end delimiters are correct.

Code to reproduce the Bug

Provide minimum code, together with imports, that we can execute to reproduce the bug.

import Foundation
/* Comment */

nef modules, version, platform

macOS playground
nef 0.6.1

Tooling

• Xcode version: 11.5

nef

Script to:

1. init playground using Bow.
2. compile playground pages - validation
3. generate documentation from playground pages

Render Markdown

Description

For now, nef allows rendering Jekyll markdown for your website; but it should be super cool if we could render standard Markdown files from Swift Playgrounds.