EECS society at Queen Mary

This is the content of the EECS Society website. You are welcome to contribute articles on any more or less technical topic.

Sharing your knowledge is cool. You can always mention in your CV that you contribute to a blog, know git, familiar with peer reviews, and able to read documentation.

You can also directly point to your work. Your next employer will definitely like it.

Writing an article

The content of the blog is hosted on github, a project hosting service. There are two ways of adding the content to the website. The simplest one is to use web interface, the most powerful is to use the git program.

To add an article using the web based interface follow these steps:

1. Get an account on github and login.

2. Create a file in the content/articles/ folder.

3. Name the file as nnn-slug.rst, where

   • nnn is a number of the article. Articles are numbered sequentially, pick the next integer from the the articles directory.
   • slug is an informative but short identifier of the article.
   • .rst is the file format we are using. It allows to define basic formatting, such as headers, links or references. Refer to the reStructuredText quick reference for examples.

4. Apart form the article, the file should contain some meta information, such as the name of the author, the date the article was written, its tags and category. Here is an example, copy, paste and modify it:

   ==========================================
   An example of an article in the rst format
   ==========================================
   
   .. Some metadata
   
   :date: 2014-04-02 15:00
   :tags: technology, example
   :category: blog
   :author: Dmitrijs Milajevs
   
   The first paragraph should introduce and possibly summarize the article.
   It should be relatively short: 2 - 3 sentences.
   
   .. Explicitly mark the end of the summary/introduction
   
   -- PELICAN_END_SUMMARY --
   
   .. Here goes the rest of the article.
   
   This is a header
   ================
   
   This is the second paragraph. You can mark some text as **bold** or `italic`.

5. Write the article!

6. Save the file by clicking a light green button in the bottom right corner of the page.

7. Now you are ready to create a pull request!

   1. Go to https://github.com/YOUR_USERNAME/qmcs.github.io/.
   2. Click on create pull request.
   3. Fill in all the relevant information.
   4. Send a pull request.

You article will be reviewed by other contributers. You might be given suggestions on how the article can be improved. Once the suggestions are implemented the article is be published!

Using git

First of all, set up an ssh key, and fork the original repo. You also need to configure git. If you didn't use git before, check out Github tutorial, a tutorial provided by Software Carpentry or Github guides to get a general idea.

1. Before writing an article, clone the repo:

git clone git@github.com:username/qmcs.github.io
cd qmcs.github.io

2. Write an article!
3. Commit and push your changes:

git st  # see what files have been changed
git diff  # see the actual changes
git add RELATED_FILES  # probably, somethig like content/articles/001-intro.rst
git ci -m'An article describing the enterprise (R) power of Java.'
git push  # send you changes to github

Create a pull request.

Personal page

You can add information about yourself, such as a brief description of who you are, your interests, your homepage and contact information, and, most importantly, a picture.

Author bibliographies are stored in content/authors. Here is an example of dmitrijs-milajevs.rst:

=================
Dmitrijs Milajevs
=================

:slug: dmitrijs-milajevs
:cover_image: static/author_images/dmilajevs.jpg
:homepage: http://www.eecs.qmul.ac.uk/~dm303/
:service__github: https://github.com/dimazest/
:service__bitbucket: https://bitbucket.org/dimazest/
:service__twitter: https://twitter.com/dimazest
:service__linkedin-square: https://www.linkedin.com/in/dmitrijsmilajevs
:cv: dmilajevs_cv.pdf


`Dima <http://www.eecs.qmul.ac.uk/~dm303/>`_ enjoys programming since he was a
teenager. He is interested in natural language processing.

-- PELICAN_END_SUMMARY --

He spends working days in his office surrounded by monitors and pile of
scientific papers. On a weekend, he escapes the office and spends most of the
day in a coffee shop somewhere in Central London. To compensate time spent
sitting, he does Modern Pentathlon.

You can find him (re)tweeting as `@dimazest <https://twitter.com/dimazest>`__
and showing off his `professional achievements`__ on Linkedin.


__ https://www.linkedin.com/in/dmitrijsmilajevs

The first paragraph should be short and clear. Note usage of -- PELICAN_END_SUMMARY -- to mark the end of the summary.

Metadata field prefixed with service__ will appear as icons to the listed websites. Use names of the services that are available in Font Awesome.

The cover image is a 461x461 picture of you or an avatar and should be located in content/static/author_images.

Put you CV to content/static/cv and add the :cv: metadata field.

Article with Cover Photo (alternative)

You can, instead of using the standard article template, use a template which includes a cover photo – much inspired from medium.com. Here is how to use it. Beware, the procedure looks different in Markdown and RST.

Meta header in Markdown:

Title: Space Kittens
Date: 2014-04-15
Tags: markdown, markup, languages
Category: languages
Author: Henrik O. Skogmo
Template: article_cover
Cover: space-cat.png

Meta header in RST:

=============
Space Kittens
=============

:date: 2014-04-15
:tags: markdown, markup, languages
:category: languages
:author: Henrik O. Skogmo
:template: article_cover
:cover: space-cat.png

1. Write your article as you would otherwise, following the Writing an article guide in this readme.

2. Change the meta template line to look like this Template: article_cover instead of Template: article. This will trigger the system to use the alternative template.

3. Add the line Cover: space-cat.png underneath. Here I use the photo named space-cat.png which I added in the folder content/static/article_covers. This is how we tell the system which photo to use as a cover photo.

Now all you have to do is commit and push your article, together with your desired photo.

Peer review

Every article should be reviewed by two people. You are welcome to go trough any open pull request and comment on the things you like or dislike. If you find the changes to be merged, write a comment:

:+1:

It's completely fine to comment about anything, but it's important to be polite, precise and constructive.

To speed up the process assign someone from the team to do peer review. If your article got comments from someone else, please fix them in a timely manner. The sooner you fix all the issues, the sooner the article appears on the website.

Generating the blog locally

We use buildout to deploy needed software. A typical biuldout deployment consists of two steps: bootstrapping and building out.

Bootstraping is simple:

python bootstrap.py

In case you get an error about setuptools, you can install them:

# Only if you get an error in the previus step!
python ez_setup.py --user
python bootstrap.py

Now you are ready to buildout:

bin/buildout

An easy way to see rendered article files

You can use restview to see rendered .rst or meow for .md files in your browser. For example:

bin/restview content/articles/001-intro.rst  # to see the intro article
bin/meow content/articles/009-markdown.md  # to see the Markdown article

There are rumors, that you can feed a directory to restview and then select files in the browser:

bin/restview content

Generating the HTML version of a blog locally

Now, you can get a local version of the blog:

make devserver
open http://localhost:8000  # gnome-open on Linux
# make stopserver is a logical way to stop the server

Developing the theme and plugins

Our blog uses a custom theme and plugins. The theme and the plugins are external projects and don't belong to this git repository! However, during the buildout step they are cloned to the src/ folder, thanks to Mr. Developer. Here are the external projects we depend on:

tree -L 1 src/
src/
├── pelican-plugins  # Extenal plugins. Don't bother about it.
├── pelican_extended_authors # Our plugin that provided authors' metadata.
└── pelicanium  # The theme we use.

Note that, by default pelicanium and pelican_extended_authors are clones of https://github.com/pyclub, but if you want to make changes to these projects you need to use your own fork! These are the steps you need to perform, to be able to push to your own fork:

1. Fork pelicanium and pelican_extended_authors in github web interface. Refer to the [sources] section of buildout.cfg to see what projects you should fork. Such projects are located under https://github.com/qmcs/.
2. Create .mr.developer-options.cfg with the following content:

[rewrites]
# Use your own forks instead of the upstream repos for the ``qmcs``projects.
qmcs =
    url ~ ^https://github.com/qmcs/
    git@github.com:YOUR_USERNAME/
    kind = git

# Use ssh instead of https for all github repos.
github =
    url ~ ^https://github.com/
    git@github.com:
    kind = git

3. Remove the src folder. Be sure that there are no any changes you want to keep. If there are, change remote urls in git repo.

rm src/ -rf  # Again, be vary careful!

4. Run bin/buildout.

Change remote urls in git repo

In case you want to push to github after you run buildout, you need to change remote urls by yourself, for example:

cd src/pelicanium
git remote set-url origin git@github.com:YOUR_USERNAME/qmcs.github.io

Update dependencies

If you want to update the dependencies, run:

bin/develop up

Add a remote

In case you want to refer not only to your repo, but to others, you need to add another remote:

git remote add upstream git@github.com:qmcs/qmcs.github.io

Now you can merge with the recent pelican branch:

git checkout pelican
git fetch upstream
git merge upstream/pelican

You can also checkout feature branches:

git checkout -b theme upstream/theme  # Get the theme branch from upstream
git push -u theme origin/theme  # Push it to your fork and set it as the default push destination

Updating the web site

In case you are lucky and have write access to the main repo you can upload the generated HTML version of the site, however you need to clone git@github.com:qmcs/qmcs.github.io.

To upload the HTML just run:

make github

License

This work is licensed under a Creative Commons Attribution 4.0 International License.