Skip to content

Latest commit

 

History

History
319 lines (194 loc) · 12.6 KB

README.textile

File metadata and controls

319 lines (194 loc) · 12.6 KB
Raw

Arquillian Website Source

This repository contains the source of the Arquillian website (hosted using github pages), to which the arquillian.org hostname resolves.

The website is built using Awestruct. The develop branch contains the unprocessed website source. From that content, Awestruct generates a static website under the _site directory. The website is published to the public site by pushing the contents of the _site directory to the master branch.

Setting Up Awestruct

You need to have Awestruct installed on your machine to preview the website locally. Awestruct is a available as Ruby gem in the GemCutter repository. You can install it into either a native Ruby or a JRuby installation. The instructions here will cover setting up Awestruct in both native Ruby and JRuby installation for Linux environment.

Begin by installing the package for Ruby and RubyGems.

Installing Ruby and RubyGems on Ubuntu

If you have Ubuntu, use this command to install Ruby and RubyGems:

$ sudo apt-get install rubygems

Ubuntu does not currently add the RubyGems bin directory to your path. Put the following files in your shell configuration file (.bashrc) and restart the shell.

$ export GEM_HOME=/var/lib/gems/1.8 \ 
export PATH=$PATH:$GEM_HOME/bin

Now the executables for any gem you install will be available on your path.

Installing JRuby on Ubuntu

It might happen that you will face similar problem while trying to install awestruct using Ruby on Ubuntu. In that case using JRuby as an alternative might solve it.

First, download and unpack latest stable version of JRuby: (The one available in Ubuntu repositories is too old and does not support Awestruct)

$ wget http://jruby.org.s3.amazonaws.com/downloads/1.6.5/jruby-bin-1.6.5.tar.gz \
tar -xzvf jruby-bin-1.6.5.tar.gz

Optionally, you can copy it to /usr/lib/jvm and create symbolic link for convenience:

$ sudo mv jruby-1.6.5/ /usr/lib/jvm \
cd /usr/lib/jvm/ \
sudo ln -s jruby-1.6.5/ jruby

Last step is adding JRuby to path (for instance in .bashrc)

$ export JRUBY_HOME=/usr/lib/jvm/jruby \
export PATH="$JRUBY_HOME/bin:$PATH"

That’s it. Just install all required gems described in subsequent sections and you are ready to run awestruct backed by JRuby!
NOTE Use jgem instead of gem for this purpose.

Installing Ruby and RubyGems on Fedora

If you have Fedora, use this command to install Ruby and RubyGems:

$ sudo yum install ruby ruby-devel ruby-irb rubygems

Optionally, you can install RubyGems manually to use a newer version (was once a requirement for installing Awestruct, but has since been fixed):

$ wget -q http://production.cf.rubygems.org/rubygems/rubygems-1.8.15.tgz \
tar xzf rubygems-1.8.15.tgz \
cd rubygems-1.8.15 \
sudo ruby setup.rb

In Fedora, RubyGems properly links applications such as awestruct to /usr/bin when the corresponding gem is installed, so no need for messing with the PATH.

Installing the Awestruct Gem

Now you are ready to install awestruct. The remainder of the commands work on any Ruby installation. If you’re using JRuby, remember to use jgem instead of gem.

Use this command to install the awestruct gem and its dependencies:

$ sudo gem install awestruct

If you get a compiler error when RedCloth is installing, use this command instead:

$ sudo gem install awestruct -- --with-cflags=\"-O2 -pipe -march=native -Wno-unused-but-set-variable\"

You’re all set!

If you’ve previously installed awestruct, make sure you have Awestruct >= 0.2.5. You can update it update it using this command:

$ sudo gem update awestruct

NOTE If you’re using JRuby, you’ll need to update your RedCloth gem to support international characters. Follow these steps:

Additional Required Gems

As the website matures, more gems will be required. This section documents the required third-party gems not already installed by Awestruct.

Install these Gems using the gem install command (or jgem install command for JRuby) as you did above.

  • rest-client
  • git
  • sassy-buttons
  • vpim
  • json
  • jruby-openssl (if using jruby)
  • rb-inotify (if using linux)

Previewing the Site Locally

Now that you have awestruct installed, you can preview the website locally by running it in development mode. Development mode uses a file monitor to automatically update the site when you make a change to the source files.

To run the site, you first need the source code. Begin by cloning the website source code from git:

git clone git://github.com/arquillian/arquillian.github.com.git

Then, switch to the develop branch (the master branch holds the published site only):

git checkout develop

Run the following command to launch the preview server:

awestruct -d

Visit the following page in your browser:

http://localhost:4242

You’re now awestruct!

If you only want to generate once when you start the server, use this command:

awestruct --server -P development

Add the --force flag to either command to regenerate the site from scratch. You can also remove the _tmp and _site directories to clean the generated files.

Conventions

Haml is the preferred abstract HTML markup language.

Textile is the preferred text markup language.

Sass and Compass are the preferred CSS frameworks.

Source files are indented using 2 spaces. Haml files require the same indentation size throughout. Ruby hashes should have no leading or trailing spaces and options such be seperated by a comma followed by a space (e.g., {:href=>"http://arquillian.org", title=>"Arquillian Project Site"}).

Note: In a HAML document, if you use the equals seperator (=) rather than a greater than equals (=>) in a hash key-value assignment, Awestruct will crash.

Page structure

  • #banner
    • h2#logo
    • #navigation
  • #main
    • #content-header
      • h1
    • #content
      • .post
        • .header
          • h2.title
          • .byline
        • .body
        • .footer
    • #sidebar
  • #footer

Writing a Blog Entry

Writing a blog entry is very easy. All you have to do is fill in a brief prolog at the top of the file, then just type your content. The rest is handled for you.

Filename

To write a blog entry, create a new textile document with the file extension .textile in the blog/ folder. The name of the file is important. It determines the date of the blog entry and the URL. The syntax is:

YYYY-MM-DD-URL.textile

You cannot use dots or spaces in the URL segment.

For example:

2011-10-02-announcing-arquillian-1-0.textile

Prolog

The prolog is a set of name/value pairs defined at the top of the file in between two lines containing three dashes. In this section you define the following metadata:

  • layout (always “blog”)
  • title (use sentence capitalization)
  • author
  • tags (array structure, limit to 5, use singular forms as in “release”)

Here’s an example (refer to HTML output):

---
layout: blog
title: Announcing Arquillian 1.0!
author: Aslak Knutsen
tags: [ announcements, releases ]
--- << only copy the hyphens and the lines of text between them

Content

Below the prolog, you just type in textile format.

Code

To insert syntax highlighted code, followed by paragraph text, use the following syntax (refer to HTML output of this guide):

public class Alien {
    public String getName() {
        return "Ike";
    }
}

This sentence will appear below the code.

You don’t normally need to use the p. prefix to enter a paragrah. However, it’s required after a code block to indicate to the parser that the code snippet has ended. If the content following the code is not paragraph text (for instance, a list item), use notextile. instead of p., but include one space at the end of the line.

The language is detected automatically.

If you are running awestruct in preview mode, you need to touch the blog/index.html.haml file to see the blog show up in the index (likely a bug).

Images

Images should be put in the images/blog/ folder. An image should be no more than 600px wide.

Writing a Release Note

Writing a release note is even easier than blog post. There is a template file created for this purpose blog/_github-release-template.textile.

Simply name your file using following convention [repository-name]-[versionId].textile (eg. arquillian-core-1.0.0.CR6.textile). Fill in the most important features which are part of this particular release.

Other things like JIRA tasks are picked up automatically.

If for some reason you are not able to see your release notes on blog/ aggregator page, perform following steps:

Delete where tag/release information is read from:

rm -rf _tmp/repos/[repo-that-contain-release]

Delete the overview from JIRA that contains all released versions:

rm -rf _tmp/jira/jira-ARQ.json

Then restart awestruct and everything should work nicely.

Writing a Guide

Writing a guide is much like writing a blog entry (and, as such, just as easy). You need to supply some prolog information, a header stating what the guide covers and content partitioned using level 3 (h3) headings. The rest is handled for you, including the table of contents and listing in the index.

IMPORTANT When committing a guide, put it in a commit by itself and use a commit message that describes to a reader what changed. Commit messages are used as the guide’s changelog.

Filename

To write a blog entry, create a new textile document with the file extension .textile in the guides/ folder. The name of the file will become the last path in the guide’s URL and thus should closely match the guide’s title. Since it’s part of the URL, the filename should not contain spaces.

Prolog

The prolog is a set of name/value pairs defined at the top of the file in between two lines containing three dashes. In this section you define the following metadata:

  • layout (always “guide”)
  • title (use title capitalization)
  • authors (comma seperated list of original authors of the guide)
  • translators (comma seperated list, for translations only)
  • tags (comma seperated list)
  • guide_summary (summary text to be used in the guide index)
  • guide_group (numeric; 1 = beginner, 2 = intermediate, 3 = advanced)
  • guide_order (numeric weight; less is more)

Here’s an example (refer to HTML output):

---
layout: guide
title: Getting Started
authors: [Dan Allen]
tags: [cdi, weld, maven, forge, eclipse]
guide_summary: Learn how to add Arquillian to the test suite of your project and write your first Arquillian test.
guide_group: 1
guide_order: 10
--- << only copy the hyphens and the lines of text between them

Content

Below the prolog, you type in textile format. (Don’t use an h2. heading for the title, it will be inserted automatically.)

You should begin each guide with a summary that lays out what the guide covers. It should be regular paragraph text surrounding a list of topics.

The remainder of the content should be divided into level 3 (h3) headings. The heading title should be no more than 20 characters and use title capitalization.

NOTE: Currently, you cannot use acronyms in the heading of a guide section.

Code

Refer to the instruction for writing a blog entry to learn how to enter code.

Images

Images should be put in the images/guides/ folder.

Textile Extensions

You can add emoticons by immediately preceding any of the following smile symbols with tilde (~):

:)
smile
;)
wink
:S
confused
:D
happy

Here’s an example ~;)

Resources