bow-swift / nef Goto Github PK
View Code? Open in Web Editor NEWπ steroids for Xcode Playgrounds
Home Page: https://nef.bow-swift.io
License: Other
π steroids for Xcode Playgrounds
Home Page: https://nef.bow-swift.io
License: Other
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.
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
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
β 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.
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.
nefc should be less verbose in output.
NEFC has 3 steps of compilation:
cocoapods
Step 3 is console user-friendly and generate logs with the outputs - in steps 1 and 2 nef
should do the same
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
We want to open nef
to developers. On this way, nef
should be easily imported into Xcode projects to expand its power.
Then we could take advantage of these renders in any other external Xcode project.
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:
nef
project should be modularized as follow:
UI
: module with the CLI dependenciesComponentes
: 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.In order to integrate the most important dependency managers in nef
, we will add support to Carthage.
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)nef playground
+ information about Carthage supportsnefc
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.
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:
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.Allow changing the background color from headers
section in md
files.
example of use
----------------
layout: docs
background: #FFFFFF
----------------
Script to generate documentation from playground page
- compatible with Jekyll
Add testing support to nef
to reduce the boilerplate for using XCTests (or any third party library).
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.
Thanks for the awesome tool!
It would be great to have SPM support!
I have a playground page that compiles normally. When adding a /* Comment */
and running nef compile I get a Syntax analysis failed
error.
I can compile the playground, it's just code and comments.
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.
Provide minimum code, together with imports, that we can execute to reproduce the bug.
import Foundation
/* Comment */
macOS playground
nef 0.6.1
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 :)
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
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
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.
β nef playground --verbose
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.
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.
We should set inner nested urls as relative as higher level ones in the docs sidebar menu.
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
We want to publish a GitHub action to let users compile its Xcode Playgrounds (no external dependencies)
it should be super cool if we could render Swift Playgrounds to PDF
files.
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:
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.
We need to allow the docs website sidebar to show nested options under some entries.
Currently only one level is supported.
We will create a logo for the nef
project.
Script to:
init
playground using Bow
.compile
playground pages - validationgenerate
documentation from playground pagesWe will implement Jekyll site to Nef library
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.
If the project name input is the same as the playground page, then jekyll
, carbon
, markdown
remove the project folder and fails.
Detect when these kinds of coincidences are given and abort CLI with a descriptive error.
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
.
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...)
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)
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:
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.
We want to publish a GitHub action to let users compile its nef Playgrounds
(with 3rd-party libraries)
Build a basic playground
with support to Bow
Before to publish the versiΓ³n 0.2.0
we need to update the README
We need to update the Markdown library to add Carbon render. Receiving a playground page library will export each Node.Code
as Carbon snippet
Add description and examples of use for the microsite.
compile
from the command line a Swift Playground project.nef Playground
Xcode Playground
with 3rd-party libraries compatibility.Swift Playground
(iPad) with 3rd-party libraries compatibility.Markdown
project from nef Playground.Jekyll site
from nef Playground.Carbon
images from nef Playground.FP architecture
has nef. I think it will be useful for landing new contributors to nef project.API nef
, for building new projects/tooling on top of nef.nef Xcode extension
and How to use it :)I run nef compile and I got an error on a playground that previously worked fine
nef compile --project SensorDocs.app/
The playground is built.
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'
macOS playground
nef 0.6.1
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.
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.
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
Carbon supports the following query parameters to customize the output:
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.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
.wt=[theme]
where [theme]
can be one of the following values: none
, sharp
, bw
.l=swift
for all our purposes.pv=[padding]px
and ph=[padding]px
where [padding]
is a positive integer.ds=true
or false
.dsyoff=[y]px
where [y]
is a positive integer number.dsblur=[x]px
where [x]
is a positive integer number.wc=true
or false
.ln=true
or false
.wa=true
or false
.wm=true
or false
.fm=[font]
where [font]
is one of the available fonts (suggested: Fira%20Code
).fs=[size]px
where [size]
is a positive integer number.lh=[percentage]%25
where [percentage]
is a positive integer number (greater than 100 for correct visualization, default to 133).es=[x]
where [x]
can be one of 1x
, 2x
or 4x
.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.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
π Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. πππ
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google β€οΈ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.