Contributing

Introduction

To submit a simple documentation change, simply edit the appropriate file on GitHub. (There’s even an Edit link in the top-right corner of each page!)

Warning

Not all markup is supported by GitHub – e.g. :ref: and :doc: – so the preview may not be exactly what appears in the online documentation. Don’t let that put you off making changes, but if you’re making substantial changes it would be better to clone the repository and test it offline first.

If you want to submit a bug fix, the information below should help you to get started. Push your changes to a new branch on GitHub, then open a pull request.

If you want to suggest a new feature, I recommend opening an issue to discuss the idea first, to make sure it will be accepted. (Or you can go ahead and develop it first if you prefer!)

System requirements

First make sure your system meets the main system requirements.

In addition, you will need:

Grunt (CLI)

To check if it’s installed:

$ grunt --version

To install it:

$ sudo npm install -g grunt-cli

Python & Sphinx

The documentation is generated by Sphinx, which is written in Python and installed with pip.

To check if they’re installed, run:

$ python --version
$ pip --version
$ sphinx-build --version

Installing Python & pip (on Debian)

$ sudo apt-get install python-pip

Installing Sphinx

$ sudo pip install sphinx sphinx-autobuild sphinx_rtd_theme

LaTeX (optional)

To build the PDF documentation, you will also need LaTeX installed. To check:

pdflatex --version

Installing LaTeX (on Debian)

$ sudo apt-get install texlive texlive-latex-extra

Installing Awe from Git

Download source code

Obtain a copy of the Awe source code, if you haven’t already. If you are planning to make changes, it is best to fork the Awe repository on GitHub first – then use your own username in place of alberon below.

You can install Awe into any location, but ~/awe/ would be a logical choice and is used below.

$ cd
$ git clone git@github.com:alberon/awe.git

Install dependencies

$ cd awe
$ npm install

This will:

  • Install Node.js dependencies using npm
  • Install Ruby dependencies using Bundler
  • Compile the source files (from IcedCoffeeScript to JavaScript)
  • Run the test suite (using Mocha)

At this point it should be possible to run Awe by specifying the path to the executable:

$ ~/awe/bin/awe --version

Make it the default version (optional)

If you would like to run awe directly, instead of using the full path, run:

$ export PATH="$HOME/awe/bin:$PATH"

This will only last until you close the terminal session.

Upgrading Awe from Git

$ cd ~/awe
$ git pull
$ npm install

Uninstalling

Simply delete the source directory:

$ cd
$ rm -rf awe

Source code

The source code is in lib/. It is written in IcedCoffeeScript – and you will need to understand defer and await as they are used extensively.

To compile it, run:

$ grunt build-lib

Alternatively, to compile everything at once (source code, documentation and man pages – excludes PDF docs):

$ grunt build

Or to build everything at once and then watch for further changes and rebuild automatically (the recommended method):

$ grunt watch

In each case the compiled JavaScript code is written to lib-build/, and you can run the bin/awe executable script to run it.

Unit tests

Please ensure that every important function and bug fix has corresponding unit tests, to ensure backwards compatibility.

The unit tests are in test/. They are written in regular CoffeeScript.

To run them all:

$ grunt test

To run a single test suite, add the filename without the extension:

$ grunt test:AssetGroup  # -> test/AssetGroup.coffee

When you run grunt watch, it will:

  • Automatically run any test suite that is modified
  • Run the appropriate test suite when any file in lib/ is modified (e.g. when lib/AssetGroup.iced is modified, test/AssetGroup.coffee will be run)

You should manually run grunt test before committing your changes, to ensure that all tests are still passing.

Documentation

Documentation is in docs/. It is written in reStructuredText and converted to HTML and PDF formats by Sphinx.

To build the HTML docs:

$ grunt build-docs-html

When you run grunt watch, it will automatically rebuild whenever a file in docs/ is modified.

Warning

When using grunt watch, Sphinx will only rebuild modified files. When one file references another (e.g. the table of contents), some information may be out of date. To force it to rebuild all files, run grunt docs manually.

PDF documentation

The PDF documentation takes several seconds to generate, so it is not built automatically. To build the PDF docs:

$ grunt build-docs-pdf

Sphinx markup reference

I found the following documents useful when writing the documentation:

Heading styles

The following code styles are used for headings:

################################################################################
 Page title (80 hashes)
################################################################################

================================================================================
 Section title (80 equals signs)
================================================================================

----------------------------------------
 Heading 2 (40 hypens)
----------------------------------------

Heading 3 (full stops)
......................

Custom admonitions

I found it necessary to make some custom admonitions (alert boxes) using HTML classes that are available in the Read the Docs theme:

.. admonition:: Alberon Note
    :class: note wy-alert-success

    This is a note for staff at Alberon specifically...

.. admonition:: Future Plans
    :class: note

    This is something I plan to add in the future...

For other classes see the Wyrm documentation.

Updating dependencies

Before updating any dependencies, remember to check the changelogs to ensure they are compatible.

Node.js

To check for updates:

$ npm outdated

To install updates:

$ npm update

(You will need to update the version number in package.json first to install some updates.)

Ruby

To check for updates:

$ bundle outdated

To update the Ruby gems to the latest version:

$ grunt update-gems

This will install the latest versions and update Gemfile.lock.

Releasing a new version

  • Check the documentation is up-to-date
  • Update Upgrading a project (if necessary)
  • Run grunt deploy