Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/titaniumbones/course-template

A template to use for new courses, and also hte help standardize old ones.
https://github.com/titaniumbones/course-template

Last synced: 4 days ago
JSON representation

A template to use for new courses, and also hte help standardize old ones.

Awesome Lists containing this project

README 

        
* Blank template for Matt Price's courses



This repo is an effort to develop standard practices around course deployment. At present my courses don't all conform to this standard, but eventually I hope they will.  By describing my processes here, I hope I will be able to standardize all my courses, write generic (rather than bespoke) deployment scripts, and ease the process of dockerizing my courses to avoid catastrophic failures (as occasionally still occur).  



** Org-mode



All my course materials are written in [[https://org-mode.org][org-mode markup]], a multi-faceted markup format that is similar to [[https://en.wikipedia.org/wiki/Markdown][markdown]], but with a much richer feature set.  Unfortunately it is almost entirely restricted to Emacs users, and perhaps because of that will never gain wide acceptance. For me, though, it remains the best way to write both code and text, and I'm likely to stick with it for the foreseeable future.  

- My course syllabus is always a stand-alone document in the top-level directory, which also contains

- [[./Lectures.org]], a single file with all my lectures

- [[./Assignments.org]], a single file with all my assignments

- [[./Grades]], a directory with my grading materials (I exclude these from my git repositories to avoid any accidental disclosure of private information)

- [[./Readings]], a directory with copies of course readings (similarly, I exclude this from my git repo for copyright reasons)

- [[./Images]] ditto



So the whole course structure comprises just a few large files, which I find a convenient way to keep track of everything. 



** Export

I use org-mode's native exporter to produce course documents that need to be distributed in other formats (usually ~.pdf~, ~.docx~, and ~.htm~ or ~.md~). Org's exporter is extremely powerful and flexible, and I use a set of configuration variables, set in the document headers, to control its behaviour. At present I still have stray bits of elisp code in my emacs configuration, but I hope to move that to a central location so its easier to reproduce my build environment.  



** Websites

Most of my courses have simple static websites, built by the [[https://gohugo.io][Hugo]] static site generator. Hugo actually supports org-mode files, but not the monolithic files that I prefer to use. So my website build process has a few steps:



1. edit the org-mode source files in this repo

2. export edits to hugo using ~ox-hugo~, check changes in a local browser, and commit

3. generate the static site by running ~hugo~ in the website directory

4. upload files to github or other static site host (like [[https://hackinghistory.ca]])



In the past this has required me to maintain 3 repos or at least 3 branches. My new plan is to cut out the intermediate step.  TThe static site "source" files (which are themselves genreated by org!) will just live in the ~website~ directory.  Auto-generated files will have to be added to git, maybe with some kind of a quick script, or just via magit.  



~website/deploy.sh~ contains a really helpful, quick deployment script. 



~.githooks/post-commit~ calls the deploy script with a commit message argument derived from the current commit. 



*** Hugo Theme requirements

I've been liking simple themes with a sidebar that takes care of the limited navigation requirements for the course.  Right now the only important extra feature I've been needing is support for fully-formed ~reveal.js~ slideshows.  Most Hugo themes with ~reveal~ support do the parsing themselves -- so they expect to see .md files.  That isn't great for me because the org-mode reveal exports are fairly opinionated, and I'd have to write a bunch of code to produce the md files in the form i want them to have.  And in some cases the md parsers might not produce the right markup anyway.  So, instead I use ~org-reveal~ to export, but filter the css and js values at the end of the process; this gives me a set of complete ~html~ files as output.  To work within the website, these files need to be set inside an iframe, or some other way of scoping css instructions.  SO I always need to write a couple of layout templates for just that purpose, as well as a menu generation method that opens the slideshows i n the right place.  



I'd be happy to have slightly more sophisticated stuff happening here, but I'm not quite there yet.  



*** ACTION insert the GH address of the source files into the commit message, to make it easier to find them on the web?



** Auto exporting

These files take advantage of the [[https://ox-hugo.scripter.co/doc/auto-export-on-saving/][auto-export functions]] in ox-hugo. So every time a Hugo source file is saved, the ~.md~ file gets exported to the Hugo site and it can be viewed in a pinned tab in a Hugo process which gets started by ~~/bin/starthugo.sh~, which starts up all the course websites at once.  



+I need to replicate ~ox-hugo-auto-export~ for ~ox-huveal~,+ which itself is a bit of a disaster and desperately needs rewriting. I have a do-what-i-mean function in my persistent ~**Scratch**~ buffer (copied from Kaushal!) for ox-huveal, and that works fine, but I still need to copy the rest of the infrastructure so I can add it as an ~after-save-hook~, and bundle it up as some kind of a package. I've copied [[https://github.com/kaushalmodi/ox-hugo/blob/master/ox-hugo-auto-export.el][ox-hugo-auto-export]] as ~ox-reveal-auto-export~ and I am now satisfied that it works well.  I'll pointto a gh repo when I have it up somewhere.  See [[https://ox-hugo.scripter.co/doc/auto-export-on-saving/][Kaushal's documentation on auto-exporting]] for hints on how to work this.  



** Simplifying the commit process



I'm hoping that the git post-commit hook included in this repo will make committing a one-stop process -- I just commit to the right branch, after which the deployment just happens automagically.  [[https://www.viget.com/articles/two-ways-to-share-git-hooks-with-your-team/][See this discussion of external git hooks]] for some manual setup that still needs to be done.  Will perhaps be tricky to do this via a dockerfile or whatever, if I eventually manage to dockerize my workflow here, which I hope to do.  

should be as simple as ~git config core.hooksPath .githooks~ but perhaps that belongs in a makefile or an init file of some kind.  



** Hugo Setup 

#+begin_src sh :tangle setup.sh

#!/bin/zsh

# only do this once!



#use this oneliner to get the location of this script

CUR=$PWD

DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null && pwd )"



cd $DIR/public

rm -rf

cd $DIR



### edit this line first! make sure you get the right info!

# also replace `master` with gh-pages if nec

git submodule add -b master [email protected]:/.github.io.git public

cd $CUR

#+end_src



** What's left to do?



- [ ] finish up huveal stuff to ease that process

- [ ] include some documentation about the reveal.js requirements for Hugo themes -- they need to be able to support org-generated reveal content

- [ ] fix citations & include ~.bibtex~ files in the template

- [X] collect stray elisp into a single coherent package

- [ ] make some kind of meta-repo with all the dependencies included

- [ ] figure out a safe way to manage Grade files, but maybe also sitll include some of the template code that I use for that sutff.

- [X] add setup.org file

- [X] determine if some kind of Canvas integration is possible.

  - [X] for instance, it looks like it's possible to [[https://community.canvaslms.com/docs/DOC-12813][download all submissions for an assignment.]] I'd like to write a [[https://www.ssocircle.com/en/developer-tutorial-saml-testing-using-curl-and-ssocheck-api/developer-tutorial-part-i-a-saml-sso-flow-from-the-command-line-with-curl/][cURL script that authenticates against the servers]] and grabs & unzips the appropriate zip file.  Not sure if that's going to be possible to do or not.