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.
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:
Get an account on github and login.
Create a file in the
content/articles/
folder.Name the file as
nnn-slug.rst
, wherennn
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.
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`.
Write the article!
Save the file by clicking a light green button in the bottom right corner of the page.
Now you are ready to create a pull request!
- Go to
https://github.com/YOUR_USERNAME/qmcs.github.io/
. - Click on create pull request.
- Fill in all the relevant information.
- Send a pull request.
- Go to
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!
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.
- Before writing an article, clone the repo:
git clone [email protected]:username/qmcs.github.io
cd qmcs.github.io
- Write an article!
- 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.
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.
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.
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.
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
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
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
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:
- Fork
pelicanium
andpelican_extended_authors
in github web interface. Refer to the[sources]
section ofbuildout.cfg
to see what projects you should fork. Such projects are located underhttps://github.com/qmcs/
. - 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/
[email protected]:YOUR_USERNAME/
kind = git
# Use ssh instead of https for all github repos.
github =
url ~ ^https://github.com/
[email protected]:
kind = git
- 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!
- Run
bin/buildout
.
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 [email protected]:YOUR_USERNAME/qmcs.github.io
If you want to update the dependencies, run:
bin/develop up
In case you want to refer not only to your repo, but to others, you need to add another remote:
git remote add upstream [email protected]: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
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
[email protected]:qmcs/qmcs.github.io
.
To upload the HTML just run:
make github
This work is licensed under a Creative Commons Attribution 4.0 International License.