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, pysal/pysal.site, contains all of the build & styling scripts to construct the submodule, pysal/pysal.github.io, which is the github page for pysal and redirected to pysal.org.

Setting up the repository

First, you need to fork 2 repos pysal/pysal.site and pysal/pysal.github.io.

Then, clone the pysal/pysal.site repository:

git clone --recurse-submodules [email protected]: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 locally:

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	[email protected]:pysal/pysal.site (fetch)
origin	[email protected]: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 [email protected]:ljwolf/pysal.site

Then, I would do the same for the submodule:

cd build/html
git remote rename origin upstream
git remote add wolf [email protected]: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.

Dealing with detached head with submodules

One thing to note about submodules is that by default they are first initialized into a detached head state. We can overcome the issue by creating a new branch temp in the submodule, then go back to the master branch, merge the branch temp to master:

cd build/html
git checkout -b temp
git checkout master
git merge temp

Now you are in the master branch. You can delete the temp branch since you won't need it:

git branch -D temp

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.

• You should update the rst files in the folder pysal.site/source to make changes to the website content.
• Once the change is made, run make html to generate new html files in the pysal.site/build/html folder.
• Then cd build/html, and commit all the changes inside build/html/ : git add ..

Error sjsrey is hitting at this point

(libpysal) src/pysal.site - [master●] » cd build/html
(libpysal) build/html - [master●] » git add .
fatal: in unpopulated submodule 'build/html'
(libpysal) build/html - [master●] » 

• Run git commit and git push ljwolf master to push the local changes to your remote copy.
• Create a Pull Request for pysal/pysal.github.io.
• Once you've made a bunch of commits to the pysal/pysal.github.io, check that back into the parent pysal.site by cd ../../ & git add . && git commit -m 'updating submodule' && git push ljwolf master and create a Pull Request for pysal/pysal.site.

---

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.