Setting up & editing pysal.github.io

This project uses a static site generator and git submodules to keep the build scripts and the user-facing html separate. The parent, github.com/pysal/pysal.site, contains all of the build & styling scripts to construct the submodule, github.com/pysal/pysal.github.io.

Setting up the repository

First, you need to clone the pysal.site repository:

git clone --recurse-submodules git@github.com:pysal/pysal.site

This sets up your local repository with the parent module, pysal.site, and the *submodule, pysal.github.io. This takes pysal.site's version of both the parent and the submodule.¹ Then, enter the parent directory:

cd pysal.site/

At this point, both the parent and the submodule will refer to their pysal remotes as origin. That is, if you check their remotes:

git remote -v

you should see:

origin	git@github.com:pysal/pysal.site (fetch)
origin	git@github.com:pysal/pysal.site (push)

Thus, I would rename origin to upstream, since we usually call our shared project repository the "upstream"

git remote rename origin upstream

and I would also add my fork of pysal.site:

git remote add wolf git@github.com:ljwolf/pysal.site

Then, I would do the same for the submodule:

cd build/html
git remote rename origin upstream
git remote add wolf git@github.com:ljwolf/pysal.github.io

Note that I've added the pysal.github.io as a submodule remote, not pysal.site. This is because the submodule refers to pysal.github.io, and contains only the static html and css files that get output by sphinx in the main pysal.site.

Checking for updates to the submodule

Sometimes, the parent might not know that the submodule has changed. To check for changes to the submodule, make sure to grab its latest changes. First, though, make sure you're in pysal.site/build/html.² Then,

git pull upstream master

If this does pull down any changes, you need to make a commit in the parent to update its knowledge of the submodule:

cd ../../
git add build/html
git commit -m 'update the submodule'

Making changes to the website

The website source is stored in pysal.site/source.

• make html
• cd build/html
• commit all the changes inside build/html/ : git add . and then git commit
• push the local changes to your remote copy git push sjsrey master
• create a pr for the public website
• Once you've made a bunch of commits to the public website, check that back into the pysal.site by git add build/html && git commit -m 'updating submodule'.

---

1: Practically, this does two things. (A), it clones pysal.site to a folder called pysal.site in your current directory. (B), it sets up pysal.site/build/html to act like a "separate" git repository, tracking github.com/pysal/pysal.github.io. This is the submodule. These work by letting the parent module not track individual changes inside the submodule. Instead, the parent module only keeps track of the commit the submodule is on. When you're in pysal.site/build/html, you're in the submodule; there, any time you use git, it's like you're in a totally separate repository for pysal.github.io. When you're somewhere else inside of pysal.site, it's like you're ignoring any individual changes underneath pysal.site/build/html, and only taking stock of pysal.site/build/html as a whole. When you git clone --recurse-submodules, you're asking pysal.site for the most recent version of pysal.site and the last time it saw pysal.github.io. If someone has changed pysal.github.io independently, you need to update the submodule before proceeding.

2: You need to be in pysal.site/build/html, so that git pulls from pysal.github.io and not pysal.site. Any time you're in pysal.site/build/html, your remotes will all point to pysal.github.io.