doc: add directions for building/pushing to live site

[michaelsevilla]

There are three branches: gh-pages, master, source. It looks like you are supposed to compile source and then push the results to master but I can't figure out how to do it.

I run Jekyll using the Docker container: jekyll/jekyll

I think eventually we want people to build the site locally before checking in their content.

[csbao]

Hi Michael,

Someone with access to the Systems github account needs to go to the systemslab.github.io repo's settings. In the GitHub pages section where it says "Your GitHub Pages site is currently being built from the master branch", change "master branch" to "gh-pages".

I think that should reflect the changes made to source.

For deployment directions, anyone who has permission to contribute directly to the repo can see the wiki entry:
https://github.com/systemslab/systemslab.github.io/wiki/Deployment

[ivotron]

I think that won't work. We've been pushing to source, not to gh-pages, so our changes won't be picked up. Also, for some reason, it seems it's not possible to change which branch is being used to generate the pages from. Can we replace the master branch with the contents of source? We can create a master-old to keep the old content.

@csbao If you have time, can you please explain why you had to create a source page? Are you using something that github's Jekyll engine cannot handle? In other words, should the page be automatically built after pushing all the Jekyll files to master?

[csbao]

Hi Ivo!

Last week, I pulled the changes from source and ran
git subtree push --prefix _site origin gh-pages
so that gh-pages now contains the HTML/CSS from the new profile updates. Basically, how this works is that Jekyll parses and processes the code from the source branch and generates HTML/CSS that will display the Systems site (all this code is located in the _site folder, which is why we want to run that command).

Previously, we were using the master branch as the production branch and literally copying and pasting everything from _site to the new branch. This was inefficient and very, very prone to merge conflicts, which is why I created the new branch "gh-pages" and started using that command to push subtree changes.

I'm not sure why we have the "development" branch; we can for sure just delete that one

We could just leave "source", "master" and "gh-pages", and not update master at all. But if that's bothersome, we could just move everything from gh-pages to master and from now on, run
git subtree push --prefix _site origin master from the source branch.

Let me know if this doesn't make sense! Thanks!