CS135 Web Site Repo

Never, ever edit the web site directly. The CS135 web site is now generated by a static site generator Hugo. When it is regenerated, whatever edits you make directly will be overwritten. Read on to learn more.

Overview

A static site generator takes input files that follow specified conventions and generates all the HTML required for the site. Advantages of a static site generator include a consistent look and feel, as well as leveraging work done by others.

The vast majority of the site is written in Markdown, a restricted but much easier to read and write language that maps to HTML. One can also use HTML directly, but if you're feeling the need to do that you should definitely check with the ISC or course coordinator first. Using raw HTML should be rare.

The web site is now under version control. This allows multiple people to work on it (hopefully) without conflict. It allows people to more easily check their work (see below) before making it live. It also allows us to know who's been doing the changes.

Directory Layout

• archetypes: The starting point for new pages. Do not change without direction from permanent staff.
• assets: Custom assets for the site (e.g. CSS). Do not change without direction from permanent staff.
• content: The content of the web site. This is the main place where things will change. Note that the directory structure corresponds directly to the table of contents structure. Pages here are generally written in Markdown, as mentioned above.
• data: Files read by templates in the course of generating the site can go here. Currently it stores data to generate the self-check exercises.
• layouts: Various kinds of templates that are used by Hugo to render the site. Do not change except for strings representing constants for the current term (e.g. link to current MarkUs instance).
• public: Where Hugo puts the rendered site. Changing anything here will be quickly overwritten.
• resources: Use currently unknown. Probably internal use by Hugo.
• static: Site-wide resources that are copied directly into public_html. Stuff like images and cgi-scripts. Note that images used for a specific page (e.g. staff photos) can be bundled in the content directory.
• themes: The theme that is applied to the content when the site is generated. Do not change.
• deploy: script used to generate the site and deploy it to public_html. Do not change without direction from permanent staff.
• deployVars: Variables used by deploy to generate the site. This is where to go to change which lecture modules are displayed, for example.

How to update the web site

Working on the web site works best if you can work LOCALLY. That is, not SSHing to the course account. Unfortunately, ISAs are not currently able to do this.

Working Locally

One-time setup:

1. Checkout the repo to your own machine: svn co svn+ssh://cs135i@linux.student.cs.uwaterloo.ca/svnrepo/TERM/web. You must have an ssh key in the cs135i account and appropriate svn permissions.
2. Ensure that Hugo (the static site generator) is installed
   1. Do a which hugo to see if it's installed
   2. If not, go to the Hugo site and install it. IMPORTANT: You need the "extended" version of Hugo. I think that's what the following does, but not positive. If you get errors with SASS, then you don't have the extended version.
      If you're on a Mac and already have homebrew installed, it's as simple as brew install hugo at the command line. If you don't have homebrew installed, you'll need to run /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" at a terminal first.
   3. If you're not on a Mac, you're on your own...

1. Change directory into the repo.
2. Do `svn up` to get the latest changes others may have made.
3. Run `hugo serve`. In your browser, go to the URL listed (probably http://localhost:1313/~cs135qa/). You should see the site as it currently exists.
4. Make your changes. When files are updated, they should be reloaded in the web browser automatically.
5. When satisfied, commit your changes (`svn up -m "DESCRIBE CHANGES"`)
6. Update the production version (see below).

Working in the Student Environment

1. Log into cs135qa, the "quality assurance" account.
2. `cd ~/web`
3. Do `svn up` to get the latest changes others may have made.
4. Make your changes to the source files.
5. Run `./deploy` in the web directory. This regenerates the web site. It needs to be regenerated for each set of changes. No auto-updating like with the local development.
6. View your changes at https://student.cs.uwaterloo.ca/~cs135qa/ (note the "qa" at the end). The deploy script will show ALL the assignments in the QA directory. It will also show all of the study modules.
7. When satisfied, commit your changes
   1. Use `svn status` or `svn st` to see the files that changed.
   2. If necessary, add any new files with `svn add FILENAME`
   3. `svn ci -m "DESCRIBE CHANGES"`).
8. Update the production version (see below)

Updating the production version

After updating the web site, either locally or in the QA account, put those changes into production:

1. Log into cs135 course account.
2. `cd web`
3. `svn up`
4. `./deploy`
5. Check your work.

Other Tasks

Releasing additional lecture Modules

The deployVars file in the web_commit directory contains variables read by the deploy script. Currently it has only one, hideLectureStart. This questionably named variable is the one to change. Lecture modules starting with that number will be hidden. It is NOT under version control so that the one in the student site can be different from the one in the test site. Change it and then run the deploy script, either manually or by commiting other changes to the svn repo.

The part of this that is not automated and must be done manually is to update the overview web page in `/content/cc/lectures/_index.md`.

Steppers

Which steppers are shown is determined by `/web/static/stepping/questions/problem-list.php`. It's pretty primitive: lines are either commented out or not. The deploy script, when used in the test account, uncomments all of them. Not very robust.

The actual organization of the steppers is determined by the subdirectories in `/web/static/stepping/qsrc`.

Covered function summary

The last slide of each module is automatically generated by the program `/slides/texsupport/find-builtins.py`. It is maintained by Cameron Morland in https://git.uwaterloo.ca/cjmorland/rackettools. There currently isn't a mechanism to keep the executable in texsupport up to date with the git repo.

Implementation Details

The contents of the web site (except for videos) is stored in the course SVN repo in the cs135i account.

There is a working copy, web_commit, in the cs135 course account. It's use is only for deployment.

Other working copies, including one in the course account, are used to make updates to the web site -- and hopefully test them.

When changes in the working copies are committed to the repository, a "hook" for "commit events" runs. It calls a script in the CS135 account that updates the web_commit working copy and then runs the deploy script. The deploy script runs Hugo to generate the site putting the output in public_html. It also adjusts permissions, looks after .htaccess files, and copies some data files.

Prepping for a new term

Stuff to remove. Remember to use the SVN commands, since this is under version control.

• Remove content/assess/post-mortem/*.pdf
• Remove content/assign/a[01][0-9]/*
• Remove content/cc/instructor_materials/*
• Remove content/cc/tutorials/*

• Remove the errors from content/cc/_index.md (hopefully they've been corrected!)
• Update content/help/personnel.md
• Update the calendar at content/_index.md Note that it is generated from the calendar in the repo.
• Update the exam info on content/assess/exams.md
• Update content/assign/_index.md. Ideally, it will have all the assignments and due dates, but with the fourth parameter set to "false" until the assignment has actually been released.
• Update the Racket version on content/assign/dr_racket.md

• Replace the course slides in content/cc/slides
• Remove the old solutions on the course web site
  • ~/protectPDF/*.pdf
  • ~/protectPDF/a[0-9][0-9]_soln
  • Leave the sample finals and midterms.
  • Edit ~/protectPDF/config.php to reflect what you did