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.

Playgrounds for Xcode can have multiple pages. When you add a new page, the file structure becomes:

Chapter\ 1.playground/
├── Pages
│   ├── My\ First\ Page.xcplaygroundpage
│   │   └── Contents.swift
│   └── My\ Second\ Page.xcplaygroundpage
│       └── Contents.swift
├── Sources
│   └── Preamble.swift
├── contents.xcplayground
└── playground.xcworkspace
    ├── contents.xcworkspacedata
    └── xcuserdata
        └── [USERNAME].xcuserdatad
            └── UserInterfaceState.xcuserstate

The default Playground (with only one page) has a file structure of:

Chapter\ 2.playground/
├── Contents.swift
├── contents.xcplayground
└── playground.xcworkspace
    ├── contents.xcworkspacedata
    └── xcuserdata
        └── [USERNAME].xcuserdatad
            └── UserInterfaceState.xcuserstate

I believe that taking advantage of this structure is better than putting everything in a single Contents.swift. This is currently just a proof of concept (not fully implemented and no tests).

Work in Progress:

• [x] Transfer the entire contents of Sources instead of looking for Sources/Preample.swift
• [x] Transfer contents of Resources from .playground to .playgroundchapter
• [x] Transfer contents of Sources from .xcplaygroundpage to .playgroundpage
• [x] Transfer contents of Resources from .xcplaygroundpage to .playgroundpage
• [x] Decide if old way (single file with //// split) should still be supported
• [x] Update documentation
• [ ] Rip out //// code
• [ ] Update tests

You can test it against this repo (the generated .playgroundbook is included in the repo).

Fixes #14.

Basically I'm splitting the project into two independent code paths: one for linting and one for rendering. Feedback welcome as always.

Left to complete:

• [x] Generate playground chapter and page directories for each chapter.
• [x] Generate a manifest for each chapter.
• [x] Generate a manifest for each page.
• [x] Copy each playground page to the approach playground chapter's page directory.
• [x] Update documentation in readme.
• [x] More UI output.

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.

This could be a very barebones solution for https://github.com/playgroundbooks/playgroundbook/issues/21

Assuming a Package.swift file specifying libraries to be used these can be copied into the .playgroundbook after being fetched by SPM.

It seems to me that SPM is the most straightforward option for including libraries in a playground book as well as having the least caveats associated with it.

A couple of tweaks to make this more useful could be:

• [x] Copy into source playgrounds to support work in Xcode
• [ ] Allow more granular destinations (chapter or page) to be specified in YAML

This PR aims to clean up the existing codebase and address #7 by adding Rubocop to the project. I've also gone ahead and had Rubocop go through and automatically fix style violations where it can, but a few still remain that I'd like to address before merging this PR.

Fixes #18.

This is a work-in-progress because I haven't had a chance to test it with Swift Playgrounds to make sure it works. It's a bit messy, might be a better way to do this in Ruby. I'll check out to see if it works next week.

Fixes #20.

Regexes gave me trouble for stripping lines like

//: Some markdown.

I originally used squeeze("\n") but that strips consecutive newlines in code, which is not good (I added a test for that). So my solution was to split based on a regex that used \n* and then join. The problem is that this adds a newline before any matched components, so I make sure to remove newlines preceding //: comments after that check. Let me know what you think, I'm sure there's a better solution.

I introduced a bug yesterday, which led to chapter names not being extracted from the hash resulting in chapter names in the Manifest.plist being "{\"name\"=>\"test_chapter\"}.playgroundchapter" instead of test_chapter.plagroundchapter.

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

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?

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.

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?

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

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.