playgroundbooks / playgroundbook Goto Github PK

instead of one big file
let the author create a separate file for each page

It seems that after merging changes to the chapter configuration in the YAML file used for rendering a book no new version was tagged.

Could a new version be released to include these changes?

As per #34.

It's as easy as copying Swift files into the Sources folder, we would need to document how playgrounds on the mac need to reference these and not copy them.

As discussed in #36 I am proposing a new layout for the chapters sections of the YAML:

Before:

chapters:
  - "Chapter 1"
  - "Chapter 2"

After:_

chapters:
  - name: "Chapter 1"
     EdgeToEdgeLiveView: true
  - name: "Chapter 2"
     EdgeToEdgeLiveView: false

A proposed implementation can be viewed in #42

These need to be URL-escaped.

Explained here.

Orta had some feedback here: #23

I was just running through Apple's example playgrounds, and their Learn to Code book fails due to its use of cutscene pages. We probably want to add a specific linter for cutscene pages in the future, but for now it'd be best to avoid throwing errors whenever the linter encounters them.

Once #1 is done.

Some new keys are required, we should require them in our yaml file.

Hi all,
Once I get the file & folder structure for a .playgroundbook, I import necessary classes and put them in the sources folder. Then, on the individual Contents.swift files for each page, I try to reference the class and initialize it, add it to the live view, etc. Not only am I unable to get any autocomplete whatsoever, it does not show any suggestions for regular UIKit and Foundation stuff, like trying to create a new variable for a view, string, etc. Even when writing in the Class file from my other project that I copied over, it compiles/shows autocomplete in the separate playground, and once put in the .playgroundbook Project, nothing.

I'm thinking that it doesn't compile anything in Xcode, and will only actually compile once you load it onto the iPad, however, it doesn't seem practical to write all my code in a separate project so that I can get completition when writing.

I will get a project uploaded shortly.

Using the structure from

• https://github.com/dbgrandi/claide-plugins/blob/claide-plugins/lib/claide/command/plugins/create.rb

We can use a template like https://github.com/dionlarson/MSPlaygroundBookStarter t make it easier for people to get started, that first step is always the most difficult.

Can include some useful Rake commands to create, publish, and ship to GitHub pages too?

edge_to_edge_live_view defaults to false but I always set it to true. live_view_mode defaults to HiddenByDefault but I always end up setting it to VisibleByDefault. I think I'd like to change these to be the new defaults, since they're the common case. @playgroundbooks/contributors any thoughts?

You could have a multi-page book ( warning, the UX for those is bad you have to mention that you need open the sidebar to change page ) which gets separated by markdowns's page break notation ---

It seems that in the book.yaml file I set options (such as having an edge-to-edge live view) on a chapter. But these options are actually properties of an individual page, not of a chapter. There is a loss of granularity here.

From playground-book-lint to just playground-book that has a lint command, and a generate command that creates a playground book from maybe like a yml file and playgrounds in the current directory. Idea via @orta.

Took a look at the Learn to Code playground book. Their main manifest includes a ImageReference key that maps to a file name in their Resources directory, and it's used as the cover image for the book in the app. This tool should support that.

The code here is a bit messy, Rubocop can clean it up.

For some reason I am not able to render the book.yaml file

Output

Rendering book.yaml...
Failed to open and parse playground chapter.
/Library/Ruby/Gems/2.0.0/gems/playgroundbook-1.1.0/lib/renderer/playgroundbook_renderer.rb:68:in `block in render': Missing valid playground for Chapter 1. (RuntimeError)
	from /Library/Ruby/Gems/2.0.0/gems/playgroundbook-1.1.0/lib/renderer/playgroundbook_renderer.rb:46:in `map'
	from /Library/Ruby/Gems/2.0.0/gems/playgroundbook-1.1.0/lib/renderer/playgroundbook_renderer.rb:46:in `render'
	from /Library/Ruby/Gems/2.0.0/gems/playgroundbook-1.1.0/bin/playgroundbook:17:in `<top (required)>'
	from /usr/local/bin/playgroundbook:22:in `load'
	from /usr/local/bin/playgroundbook:22:in `<main>'

Note: I wasn't able to install playgroundbook as described in the readme. When I tried to run

sudo gem install playgroundbook

I got this error

ERROR:  While executing gem ... (Errno::EPERM)
    Operation not permitted - /usr/bin/playgroundbook

So I had to install it like this

sudo gem install -n /usr/local/bin playgroundbook

Output

Successfully installed playgroundbook-1.1.0
Parsing documentation for playgroundbook-1.1.0
1 gem installed

Playground pages can be modified with various arguments (Source]:

Currently we support LiveViewEdgeToEdge, LiveViewMode and Name.

The manifest.plist is written in lib/playgroundbook/page_writer.rb and can easily be extended with the missing parameters described above.

This can be a good first step for someone who is looking to contribute.

In the sample code provided by Apple called TalkingToTheLiveView, for each page there is a LiveView.swift file that contains few lines of code

import PlaygroundSupport
let page = PlaygroundPage.current
page.liveView = FaceViewController()

Those files are located besides Contents.swift inside each .playgroundpage folder.

I find them very useful if the reader shouldn't be able to mess with most of the code of the Live View, but instead just interact with it through the PlaygroundSupport Module.

I don't have specific tests but probably the LiveView.swift file won't be recompiled each time the editor is updated, to achieve optimal performances.

Something to do with the new book yaml format.

Things like LiveViewMode can be HiddenByDefault or some other values. Apple's documentation isn't exhaustive.

From #29.

Specially comments to direct the user start with //#-, we should warn if the string following that doesn't match a known pattern.

Things like missing Name values in a manifest shouldn't stop the rest of the book from being linted. Things like a missing /Pages directory are fatal, since the linter cannot continue if it's missing.

Code blocks like this come out with extra whitespace around them:

//// Page whatever

doSomething()

/*:
 Text
*/

Is translated to:

doSomething()

With extra newlines at the bottom.

A PR fixing this issue should strip whitespace from the beginning/end of a page's code.

Glossaries are a really cool feature, and I think this tool needs to support them. They're easy enough to use, just a plist that's a literal dictionary, but they have this "First Use" thing that gets tricky. Here's an amended example from one of Apple's books:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Terms</key>
    <dict>
        <key>while loop</key>
        <dict>
            <key>Definition</key>
            <string>A block of code that runs for as long as a given condition is true. When the condition changes to false, the loop stops running. 
</string>
            <key>FirstUse</key>
            <dict>
                <key>PageReference</key>
                <string>While%20Loops/Introduction</string>
                <key>Title</key>
                <string>While Loops</string>
            </dict>
        </dict>
    </dict>
</dict>
</plist>

I haven't figured out what the PageReference or Title are for yet. Help would be appreciated.

Currently there is no implementation for cutscenes, but it seems it should be easy to add it (Reference).

Cutscenes are located between one or more .playgroundpages and can illustrate the things discussed in the following pages.

Their Manifest.plist file is simple:

And the folder structure is as follows:

└── Intro.cutscenepage
    ├── Manifest.plist
    └── Resources
        └── hello.html

I mentioned this last night on Twitter and I'm happy to work on it. I just want a bit of advice on how you think the best way to approach it would be. I was thinking integration with cocoapods.

Thoughts?