coursegen 0.8.3 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 193bc70f31c3ec3619227c3013d0daacfa6ca097dbf6e3c48b3770b4323520e7
-  data.tar.gz: be195c77f63bf0ec888e538a17aeae4f295b48ab1131afe38d0540f92ffb2b66
+  metadata.gz: 2c8c20c18654bed952a0b1f5e488977f54e613bb0a0c6934e472d028a4abed89
+  data.tar.gz: 8db99fc9a6fa6aea08b9b6dd4d1f6de1a1e3a9b7e1757f1305482ac781bccd89
 SHA512:
-  metadata.gz: 9148e0625c30a5b78b73174890a603fa2d17d6d9df676f206510bc2d72b209b542529294942d513f67c894fc705dec67611ac9a576bf7b0276b13564c9e5ba80
-  data.tar.gz: 428fc6c4b5be13d3c229da992a3cbe985e62afae45b73562884022ea5992e0173a606e0133c1304b0af9fe8073deab496829ed9286f619b4eafbbb117fbfb1e8
+  metadata.gz: 4ab21fdc5c79763690101f1ddd93ff37ec94d26033e6d6f0f35f20ce65bee9d4e7294b2ee5bb667d6319455662fa9b258c231bba79e1b181d072f577049f962f
+  data.tar.gz: 981f8abcb7940b83582b8dbb998449871acf2d8a8704d7b575cd8b1b6a072287916850a0187bf0e3dc45f6a50deec36b8843f1b1f8ea7039813b0dabc265e46e

data/.github/workflows/pr.yml

@@ -0,0 +1,19 @@
+env:
+  RUBY_VERSION: 2.6
+name: Gem build
+on: [pull_request]
+jobs:
+  rspec-test:
+    name: RSpec
+    runs-on: ubuntu-18.04
+    steps:
+      - uses: actions/checkout@v1
+      - uses: actions/setup-ruby@v1
+        with:
+          ruby-version: ${{ env.RUBY_VERSION }}
+      - name: Install dependencies
+        run: |
+          gem install bundler
+          bundler install
+      - name: Run tests
+        run: bundler exec rake spec

data/.gitignore

@@ -2,3 +2,6 @@ pkg/*
 *.gem
 .idea/*
 *.log
+*.iml
+.byebug_history
+test_course

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    coursegen (0.8.3)
+    coursegen (0.9.1)
       activesupport
       adsf
       byebug
@@ -19,31 +19,31 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (6.0.2.1)
+    activesupport (6.0.3.1)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 0.7, < 2)
       minitest (~> 5.1)
       tzinfo (~> 1.1)
-      zeitwerk (~> 2.2)
+      zeitwerk (~> 2.2, >= 2.2.2)
     addressable (2.7.0)
       public_suffix (>= 2.0.2, < 5.0)
     adsf (1.4.3)
       rack (>= 1.0.0, < 3.0.0)
-    byebug (11.1.1)
-    coderay (1.1.2)
+    byebug (11.1.3)
+    coderay (1.1.3)
     colored (1.2)
     concurrent-ruby (1.1.6)
-    cri (2.15.9)
+    cri (2.15.10)
     ddmemoize (1.0.0)
       ddmetrics (~> 1.0)
       ref (~> 2.0)
     ddmetrics (1.0.1)
     ddplugin (1.0.2)
-    diff-lcs (1.3)
+    diff-lcs (1.4.4)
     equatable (0.6.1)
-    ffi (1.12.2)
+    ffi (1.13.1)
     formatador (0.2.5)
-    guard (2.16.1)
+    guard (2.16.2)
       formatador (>= 0.2.4)
       listen (>= 2.7, < 4.0)
       lumberjack (>= 1.0.12, < 2.0)
@@ -58,35 +58,41 @@ GEM
       guard-compat (~> 1.0)
     hamster (3.0.0)
       concurrent-ruby (~> 1.0)
-    i18n (1.8.2)
+    i18n (1.8.3)
       concurrent-ruby (~> 1.0)
     icalendar (2.6.1)
       ice_cube (~> 0.16)
     ice_cube (0.16.3)
-    json (2.1.0)
+    json (2.3.0)
     json_schema (0.20.8)
-    kramdown (2.1.0)
+    kramdown (2.2.1)
+      rexml
     listen (3.2.1)
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
-    lumberjack (1.1.1)
-    method_source (0.9.2)
+    lumberjack (1.2.5)
+    method_source (1.0.0)
     mini_portile2 (2.4.0)
-    minitest (5.14.0)
-    nanoc (4.11.14)
+    minitest (5.14.1)
+    nanoc (4.11.16)
       addressable (~> 2.5)
       colored (~> 1.2)
-      nanoc-cli (= 4.11.14)
-      nanoc-core (= 4.11.14)
+      nanoc-checking (~> 1.0)
+      nanoc-cli (= 4.11.16)
+      nanoc-core (= 4.11.16)
+      nanoc-deploying (~> 1.0)
       parallel (~> 1.12)
       tty-command (~> 0.8)
       tty-which (~> 0.4)
-    nanoc-cli (4.11.14)
+    nanoc-checking (1.0.0)
+      nanoc-cli (~> 4.11, >= 4.11.15)
+      nanoc-core (~> 4.11, >= 4.11.15)
+    nanoc-cli (4.11.16)
       cri (~> 2.15)
       diff-lcs (~> 1.3)
-      nanoc-core (= 4.11.14)
+      nanoc-core (= 4.11.16)
       zeitwerk (~> 2.1)
-    nanoc-core (4.11.14)
+    nanoc-core (4.11.16)
       ddmemoize (~> 1.0)
       ddmetrics (~> 1.0)
       ddplugin (~> 1.0)
@@ -96,26 +102,44 @@ GEM
       tomlrb (~> 1.2)
       tty-platform (~> 0.2)
       zeitwerk (~> 2.1)
+    nanoc-deploying (1.0.0)
+      nanoc-checking (~> 1.0)
+      nanoc-cli (~> 4.11, >= 4.11.15)
+      nanoc-core (~> 4.11, >= 4.11.15)
     nenv (0.3.0)
-    nokogiri (1.10.8)
+    nokogiri (1.10.9)
       mini_portile2 (~> 2.4.0)
     notiffany (0.1.3)
       nenv (~> 0.1)
       shellany (~> 0.0)
     parallel (1.19.1)
-    pastel (0.7.3)
+    pastel (0.7.4)
       equatable (~> 0.6)
       tty-color (~> 0.5)
-    pry (0.12.2)
-      coderay (~> 1.1.0)
-      method_source (~> 0.9.0)
-    public_suffix (4.0.3)
+    pry (0.13.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    public_suffix (4.0.5)
     rack (2.2.2)
-    rake (13.0.0)
-    rb-fsevent (0.10.3)
+    rake (13.0.1)
+    rb-fsevent (0.10.4)
     rb-inotify (0.10.1)
       ffi (~> 1.0)
     ref (2.0.0)
+    rexml (3.2.4)
+    rspec (3.9.0)
+      rspec-core (~> 3.9.0)
+      rspec-expectations (~> 3.9.0)
+      rspec-mocks (~> 3.9.0)
+    rspec-core (3.9.2)
+      rspec-support (~> 3.9.3)
+    rspec-expectations (3.9.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-mocks (3.9.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-support (3.9.3)
     rubytree (1.0.0)
       json (~> 2.1)
       structured_warnings (~> 0.3)
@@ -124,15 +148,15 @@ GEM
     structured_warnings (0.4.0)
     thor (1.0.1)
     thread_safe (0.3.6)
-    tomlrb (1.2.9)
-    tty-color (0.5.0)
+    tomlrb (1.3.0)
+    tty-color (0.5.1)
     tty-command (0.9.0)
       pastel (~> 0.7.0)
-    tty-platform (0.2.1)
-    tty-which (0.4.1)
-    tzinfo (1.2.6)
+    tty-platform (0.3.0)
+    tty-which (0.4.2)
+    tzinfo (1.2.7)
       thread_safe (~> 0.1)
-    zeitwerk (2.2.2)
+    zeitwerk (2.3.0)
 
 PLATFORMS
   ruby
@@ -141,6 +165,7 @@ DEPENDENCIES
   bundler
   coursegen!
   rake
+  rspec
 
 BUNDLED WITH
    2.1.4

data/README.md

@@ -1,79 +1,295 @@
 # Coursegen
 
-Generates course curriculum web sites with support for sections, lectures, code examples, homeworks, course calendar and lots more.
+Coursegen is a course curriculum site generator based on [nanoc](https://github.com/nanoc/nanoc), with support for sections, lectures, code examples, homeworks, course calendar and lots more.
 
-# Work in progress
+## Work in progress
 
 This gem is still under development. In the current form it can already be used but I will be adding more convenience features in the near future.
 
-# Steps to building a new course
-
-### Install 
-* install the gem, `gem install coursegen`
-
-### Generate Blank Course
-* generate a blank course site `gem new MYCOURSE`. This will create a local directory called MYCOURSE containing the skeleton
-* `cd MYCOURSE`
-* Load up the template and basics into the newly created directory `cg prepare`
-* Modify the configuration of the course by editing the file `cg_config.rb`. You can look at a complicated example to see some of the things that are possible: `cg_config.rb_sample`
-
-### Add it to github (optional)
-* Create a new github repo with the course name
-* `cd MYCOURSE; git init`
-* Follow Github instructions to push the first commit up to github
-
-### Steps to develop the course 
-* Add your course content as new files into the content/ directory
-* Rebuild the course static html: `cg compile`
-* Start a local server for testing: `cg serve`
-* Open your web browser to look at the course: `cg view`
-* Rinse, dry and repeat
-
-### Steps for deploying the course
-* The /output directory is a complete self-contained static html site. You can deploy it anywhere.
-* I recommend Amazon S3 for a free site
-
-### Create an S3 instance to host the site (optional)
-* Log into aws.amazon.com and look for the management console for S3
-* Create a new bucket. Call it whatever you want.
-* Look in the properties and choose "Static Website Hosting". Enable it and set index.html as your index document
-* Make a note of the "endpoint url"
-* Click on permissions/add more permissions
-* Choose Grantee: Everyone; And "list" and no others
-* Click "Edit Bucket Policy". Paste this into your bucket policy and save. Notice you have to edit "yourbucketname" to be your bucket name
-
-    {
-      "Version": "2008-10-17",
-      "Id": "Policy1",
-      "Statement": [
-        {
-          "Sid": "Stmt1",
-          "Effect": "Allow",
-          "Principal": {
-            "AWS": "*"
-          },
-          "Action": "s3:GetObject",
-          "Resource": "arn:aws:s3:::yourbucketname/*"
-        }
-      ]
-    }
-
-### Deploy to S3 (optional)
-* I've used `s3cmd` with great success. You can find it at s3tools.org. Follow their instructions to install it.
-* Configure your course to point to the bucket you just created. Notice, we are using the bucket name not the url: `AWS_BUCKET = "cosi165-2014"`
-
-### Examples
-* A simple example: https://github.com/pitosalas/jbscosi2014
-* A complex example (but based on a previous version): https://github.com/pitosalas/cosi236b
-* The resultant web site: bit.ly/cosi236b
+# Table of Contents
+
+- [Install](#install)
+  - [Prerequisites](#prerequisites)
+- [Getting Started](#getting-started)
+  - [Generating a blank course](#generating-a-blank-course)
+  - [Adding course to Github (Optional)](#adding-course-to-github-optional)
+  - [Adding a lecture](#adding-a-lecture)
+  - [Developing locally](#developing-locally)
+  - [Deploying to S3](#deploying-to-s3)
+  - [Search](#search)
+- [Configuration](#configuration)
+- [Examples](#examples)
+  - [Lectures](#lectures)
+  - [Course Sites](#course-sites)
+- [Features](#features)
+  - [Slides](#slides)
+- [Open Source Catalog of Topics](#open-source-catalog-of-topics)
+- [Using course contents from another folder](#using-course-contents-from-another-folder)
+- [License](#license)
+
+## Install
+
+### Prerequisites
+
+Before installing Coursegen, make sure the following tools are installed.
+
+- [Ruby >= 2.6](https://www.ruby-lang.org/en/documentation/installation/)
+- [s3cmd](https://github.com/s3tools/s3cmd) (for deploying to AWS S3)
+
+Using Coursegen is easy. Install the gem using rubygem.
+
+```bash
+gem install coursegen
+```
+
+## Getting Started
+
+While you are welcome to provide your own organization, typically a Coursegen-based application will follow the following organizational structure:
+
+```bash
+├── Guardfile
+├── Rules
+├── cg_config.rb
+├── cg_config.rb_sample
+├── content
+│   ├── bootstrap
+│   ├── content
+│   └── images
+├── layouts
+│   ├── banner.html.erb
+│   ├── body_footer.html
+│   ├── body_header.html.erb
+│   └── ...
+├── lib
+│   └── default.rb
+├── nanoc.yaml
+└── output
+```
+
+### Generating a blank course
+
+First, use `cg new` to create a new course named "MYCOURSE" locally containing the course skeleton.
+
+```bash
+cg new MYCOURSE
+```
+
+Next, go into the newly created directory and use `cg prepare` to load up the template and basics.
+
+```bash
+cd MYCOURSE; cg prepare
+```
+
+### Adding course to Github (Optional)
+
+Follow [Github's instructions](https://help.github.com/en/github/importing-your-projects-to-github/adding-an-existing-project-to-github-using-the-command-line) to create a Github repo for the site.
+
+### Adding a lecture
+
+All the course's materials are located under `content/content`.
+
+```bash
+content
+└── content
+    ├── extras
+    ├── index.md.erb
+    ├── intro
+    └── lectures
+```
+
+And inside of `lectures` you can find files named like this: `01_first_lecture.md.erb`. These are the lecture files. Each lecture is a erb file with a markdown syntax, here's a lecture example.
+
+```erb
+---
+title: Second Lecture - Here we go
+---
+### Continuing
+This page is the second one in the first part. It is the second lecture of the Sample Course.
+```
+
+See [Examples](#examples) for more details.
+
+### Developing locally
+
+Coursegen gives you the ability to see your changes on the fly using a combination of `cg compile`, `cg serve`, and `cg view`.
+
+First, `cg compile` rebuilds the course static html, and save to `/output` based on the newest changes:
+
+```bash
+cg compile
+```
+
+Then, `cg serve` starts a local webserver running the compiled course site:
+
+```bash
+cg serve
+```
+
+Lastly, `cg view` opens up your web browser to see the latest change:
+
+```bash
+cg view
+```
+
+### Deploying to S3
+
+Coursegen natively supports deploying the course site to AWS S3 service. Before proceeding, makes sure `s3cmd` is installed and correctly configured ([Instructions for setting up](https://github.com/s3tools/s3cmd#simple-s3cmd-howto)).
+
+To host the course site on S3, you need to create a S3 bucket. Follow [this guide](https://docs.aws.amazon.com/AmazonS3/latest/user-guide/static-website-hosting.html) for creating a S3 bucket.
+
+After the S3 bucket is created, you can deploy the course site using `cg deploy`. `AWS_BUCKET` is the name of the S3 bucket.
+
+```bash
+AWS_BUCKET="cosi165-2014" cg deploy
+```
+
+### Search
+
+Coursegen uses [DocSearch by Algolia](https://docsearch.algolia.com/) to power its search. DocSearch is an external service that indexes the site, and provides search functionality through their API.
+
+1. Create an application on Algolia (Community Plan is enough for our use case), note the `Application ID`.
+2. Create an index named "search", `Indices -> Create Index`.
+3. Note the Search-Only API Key `API Keys -> Your API Keys`.
+
+Update the following block in `cg_config.rb`,
+
+```ruby
+SEARCH_CONFIG = {
+  api_key: '<API_KEY>',
+  index_name: 'search',
+  app_id: '<APP_ID>',
+  debug: false
+}
+```
+
+## Configuration
+
+The list of configuration directives, and their meaning and intended usage is available in the self documented `cg_config.rb`.
+
+## Examples
+
+### Lectures
+
+```erb
+---
+title: Plan of Attack
+---
+<%= homework_hdr %>
+* How does a browser process a URL? When I type http://www.salas.com:8080/toplevel?p=1 what happens inside the browser, what actions does it take, what messages does it send out, what messages does it receive? <%= deliverable "Research this on the web or in books and come up with a numbered list of actions, with each step in the list being a link to a source on the web that you used to figure that out." %>
+* <%= deliverable "Programming Assignment 2" %> (Look at <%= link_to_pa :PA2 %> for details) <%= nb ": Extension! Post wherever you are so far, indicate whether you are done or not (to let us know to look at it) but you have until Monday Feb 3 to hand this in." %>
+
+#### Discussion
+* Ruby Homework tips
+	* Narrate your screencasts
+	* Run from the command line, not irb or pry
+	* Try to make the output legible not just a screen full of numbers!
+	* 1 or 2 Ruby Questions
+	* How 'require' works, and require_relative
+
+#### Products: Plan of Attack
+
+##### Iter2 - "Hello World"
+* Prepare "dossier" for reviewer as a Google Drive
+	* Paper prototype
+	* Screen Flows
+	* Schema in detail
+	* Pivotal tracker with lots of stories, prioritized
+	* Identify and research 'difficult tech issues'
+* Complete Model
+* Initial set of controller and views
+* authentication
+* Initial build
+
+##### Iter 3 -  "Pre-Alpha"
+* Update "dossier", meet with reviewer
+* Cloud deployment
+* Unit testing
+* Feature work
+* Prettier html, css, javascript
+* Integration testing
+* Continuous integration
+
+##### Iter 4 - "MVP"
+* Update "dossier", meet with reviewer
+* Initial beta users, get feedback
+* Complete MVP feature set
+* Beautiful user interface
+
+##### Iter 4 - "Unveiling"
+* Update "dossier", meet with reviewer
+* Final touches
+* Presentations
+
+#### Iter2: In more detail
+* Each team tee up a discussion about your product
+* <%= discussion "What are \"difficult technical issues?\"" %>
+* <%= discussion "Reviewers" %> (<%= link_to_incubator :reviewer %>)
+
+#### Look at next class
+* Review Paper Prototyping homework for: <%= link_to_lecture :dossier %>
+```
+
+For more complex example of lectures see [here](https://github.com/pitosalas/cosi236b/tree/master/lectures).
+
+### Course sites
+
+- An simple example: <https://github.com/pitosalas/jbscosi2014>
+- A complex example (but based on a previous version): <https://github.com/pitosalas/cosi236b>
+- The resultant web site: <https://bit.ly/cosi236b>
+
+## Features
+
+### Slides
+
+*!!! Slides generation is currently in preview stage !!!*
+
+To enable slides generation in a specific lecture, add `slides: true` to the header of the markdown file.
+
+```markdown
+---
+title: Some Lecture
+slides: true
+---
+...
+```
+
+Coursegen uses the tag `<%= slide %>` to properly separate each slide.
+
+```erb
+# Slide 1
+* some lines
+* some lines
+
+<%= slide %>
+
+# Slide 2
+* some lines
+```
+
+To disregard some content from rendering into the slides, add the html element into `cg_config.rb`.
+
+```ruby
+SLIDES_CONFIG = {
+  # This ignores any element that is <h4>
+  ignore_selector: ['h4']
+}
+```
 
 ## Open Source Catalog of Topics
-CourseGen comes with a large, shared catalog of topics. Depending on what you teach you may or may not find useful content there. Over time we hope to broaden this catalog. You can review the current set of topics here: https://github.com/pitosalas/coursegen-topics
 
-### Step by step
-* First clone the topic directory to your local drive: `git clone git@github.com:pitosalas/coursegen-topics.git`
-* Add a symbolic link between your course and the newly cloned directory. For example you might do this:
-    cd MYCOURSE/content
-    ln -s TOPICDIR .
-   
+Coursegen comes with a large, shared catalog of topics. Depending on what you teach you may or may not find useful content there. Over time we hope to broaden this catalog. You can review the current set of topics here: <https://github.com/pitosalas/coursegen-topics>
+
+## Using course contents from another folder
+
+Coursegen allows course contents to be located outside of the site folder. This is the preferred pattern, used by most coursegen courses.
+
+To connect them together, simply add a symbolic link between the course and the contents:
+
+```bash
+cd MYCOURSE/content
+ln -s TOPICDIR .
+```
+
+## License
 
+Coursegen is released under the MIT license. See [LICENSE.txt](LICENSE.txt)