The basics¶

The website is located in a Git repository. This is a distributed version control system that will allow us to maintain the website all together without the need for a central gatekeeper. To edit the website you need SSH access to Hydra and a machine with Git installed. If your personal desktop doesn’t have that, you can simply log into Hydra first and do the work there. This is what I’ll do in this guide.

Once you are on Hydra, go into a directory of your choice, where you want to host your personal clone of the webpage. In this directory run

git clone /srv/git/haxbylab.dartmouth.edu.git

This will create the clone in a sub-directory ‘haxbylab.dartmouth.edu.git’.

mih@head1 ~ % ls -l haxbylab.dartmouth.edu
total 8
-rw-rw-r-- 1 mih mih 2062 Feb 20 10:08 Makefile
drwxrwxr-x 6 mih mih 4096 Feb 20 10:08 source/
drwxrwxr-x 2 mih mih   30 Feb 20 10:08 sphinxext/
drwxrwxr-x 3 mih mih   21 Feb 20 10:08 utils/

This is what you’ll get. You don’t need to worry about any of the directories, but ‘source’. In this directory you’ll find all the pages.

mih@head1 ~ % ls -l haxbylab.dartmouth.edu/source
total 36
-rw-rw-r-- 1 mih mih 8405 Feb 20 10:08 conf.py
-rw-rw-r-- 1 mih mih 1025 Feb 20 10:08 index.rst
drwxrwxr-x 3 mih mih   78 Feb 20 10:08 internal/
drwxrwxr-x 3 mih mih   16 Feb 20 10:08 pics/
-rw-rw-r-- 1 mih mih   68 Feb 20 10:08 positions.rst
drwxrwxr-x 2 mih mih 4096 Feb 20 10:08 ppl/
-rw-rw-r-- 1 mih mih  454 Feb 20 10:08 publications.rst
-rw-rw-r-- 1 mih mih 1864 Feb 20 10:08 research.rst
-rw-rw-r-- 1 mih mih  155 Feb 20 10:08 software.rst
drwxrwxr-x 2 mih mih   64 Feb 20 10:08 _static/

All files with an ‘.rst’ extension correspond to an actual page on the website. Subdirectories without a leading underscore represent “sections” of the website. All .rst files are simple text files that can be modified with _any_ text editor – no special gear is required. Take a look into these files to get a feeling of how they are structured. The markup language used in them is called ‘restructured text’ and aims to be both flexible and human-readable in text form. For a quick summary of the syntax please glance over this page:

http://sphinx.pocoo.org/rest.html

Trust me, it is very intuitive and required virtually no overhead in comparison to writing a plain text document.

The personal pages are hosted in the ppl directory.

mih@head1 ~ % ls -l haxbylab.dartmouth.edu/source/ppl
total 40
-rw-rw-r-- 1 mih mih   38 Feb 20 10:08 andy.rst
-rw-rw-r-- 1 mih mih  338 Feb 20 10:08 courtney.rst
-rw-rw-r-- 1 mih mih   79 Feb 20 10:08 ida.rst
-rw-rw-r-- 1 mih mih  131 Feb 20 10:08 index.rst
-rw-rw-r-- 1 mih mih   80 Feb 20 10:08 jason.rst
-rw-rw-r-- 1 mih mih   85 Feb 20 10:08 jim.rst
-rw-rw-r-- 1 mih mih 3478 Feb 20 10:08 michael.rst
-rw-rw-r-- 1 mih mih 1562 Feb 20 10:08 swaroop.rst
-rw-rw-r-- 1 mih mih 3528 Feb 20 10:08 yarik.rst
-rw-rw-r-- 1 mih mih 1686 Feb 20 10:08 yu-chien.rst

You’ll have no trouble finding your’s. It is probably a good idea to simply copy the parts from other people’s pages that you like.

Once you have done youe modification you need to commit it to the repository to actually make it visible. To be able to do that you need to perform a very quick initial setup. That only needs to be done once in a lifetime and never again. Just run this:

git config --global user.name "FirstName LastName"
git config --global user.email "user@example.com"

... and of course replace the placeholders with your name and email address. Once you have done that you’ll be able to do this:

git commit -a -m "This is my very short summary of what I modfied(and maybe why)"

Note, this and all following commands need to be executed in the Git repository clone (i.e. haxbylab.dartmouth.edu/)

This command will take your modifications and commit them into your repository and attach this message to create the history of modifications of the webpage.

LAST STEP: You need to share or push you commits back into the main repository. Simply run:

git push

(if this fails, don’t worry – send me an email with the output and we’ll sort it out – most probably a problem with our initial setup...)

That should be it. At some point the website will be re-rendered with your modifications included.

For later: Whenever you want to make another modification later on. Just go back into the directory with your clone and run:

git pull

This will fetch all modifications done by other people. Afterwards proceed as described above (no need to clone again, just edit and commit).

If anything is unclear or doesn’t work – let me know!

Bibliographies¶

The joint bibliography of the whole lab is located in your website clone in the directory source/_static/ in the file haxbylab.bib. This bibliography is in the BibTex format (very mature format, over two decades in production). You can modify this file with a text editor, or with a dedicated BibTex editor. If you don’t already use some, you may consider JabRef – works on any system.

If you already use a reference manager, you can probably convert your bibliography into Bibtex format easily.