bash
html
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 <documentation-build>
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!)
First make sure your system meets the main system requirements <requirements>
.
In addition, you will need:
To check if it's installed:
$ grunt --version
To install it:
$ sudo npm install -g grunt-cli
The documentation is generated by Sphinx, which is written in Python and installed with pip. I also recommend using virtualenv to create an isolated environment for installing packages, though this is optional.
To check if they're installed, run:
$ python --version
$ pip --version
$ virtualenvwrapper
$ sphinx-build --version
$ sudo apt-get install python-pip
$ sudo pip install virtualenvwrapper
$ source /usr/local/bin/virtualenvwrapper_lazy.sh
You should also add this code to your .bashrc
file to load it automatically in the future:
if [ -f /usr/local/bin/virtualenvwrapper_lazy.sh ]; then
source /usr/local/bin/virtualenvwrapper_lazy.sh
fi
$ mkvirtualenv awe
Then in future sessions you can switch back to that environment before running grunt
:
$ workon awe
$ pip install -r requirements.txt
Warning
Grunt will fail to run if Sphinx is not installed. (It could be modified to skip the documentation build instead, but I don't want to encourage you not to update the documentation!)
To build the PDF documentation, you will also need LaTeX installed. To check:
pdflatex --version
$ sudo apt-get install texlive-full
Note
The texlive-full
package is very big. You should be able to get away with sudo apt-get install texlive texlive-latex-extra
instead, but I haven't tested it! (Source)
Obtain a copy of the Awe source code, if you haven't already. If you are planning to make changes, it is easiest 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
$ 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
If you would like to run awe
directly, instead of using the full path, you can use one of the following options:
$ export PATH="$HOME/awe/bin:$PATH"
You can make this change permanent by adding it your .bashrc
file.
Alternatively you can install it system-wide using npm. This has the advantage of allowing you to test the manual page (man awe
) as well, but it's best to avoid this method on a multi-user system as it will replace any other versions that are installed. :
$ sudo npm uninstall -g awe # Remove currently installed version, if any
$ sudo npm link
Note
You may get the following warning messages due to npm security restrictions, but they can be ignored as long as you ran npm install
above:
npm WARN cannot run in wd awe@1.0.0 bundle install --path=ruby_bundle --binstubs=ruby_bundle/bin --deployment --without=development
npm WARN cannot run in wd awe@1.0.0 grunt build test
To remove it later:
$ sudo npm uninstall -g awe
$ cd ~/awe
$ git pull
$ npm install
If you have made it the system-wide default version, remove it as shown above -- then simply delete the source directory:
$ cd
$ sudo npm uninstall -g awe
$ rm -rf awe
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 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
This is the default command, so you can shorten it to:
$ grunt
In each case the compiled JavaScript code is written to lib-build/
, and you can run the bin/awe
executable script to run it.
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. whenlib/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 is in docs/
. It is written in reStructuredText and converted to HTML and PDF formats by Sphinx.
To build the HTML docs:
$ grunt docs
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.
The PDF documentation takes several seconds to generate, so it is not built automatically. To build the PDF docs:
$ grunt pdfdocs
I found the following documents useful when writing the documentation:
- reStructuredText quick reference
- Admonitions list (
note::
,warning::
, etc.) - Code examples markups (
code-block::
,highlight::
) - Other paragraph-level markup (
versionadded::
,deprecated::
, etc.) - Inline markup (
:ref:
,:doc:
, etc.) - Table of contents (
toctree::
)
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)
......................
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.
Before updating any dependencies, remember to check the changelogs to ensure they are compatible.
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.)
To check for updates:
$ bundle outdated
To update the Ruby gems to the latest version:
$ grunt bundle
This will install the latest versions and update Gemfile.lock.
To check for updates:
$ pip list --outdated --local
To upgrade a package:
$ pip install --upgrade <name>
To save the modified versions:
$ pip freeze > requirements.txt
- Run
git pull
to ensure all changes are merged - Test with
grunt test
- Check the documentation is up-to-date
- Update the
changelog
- Run
npm version X.Y.Z
to updatepackage.json
- Run
git push && git push --tags
to upload the code and tag to GitHub - Run
npm publish
to upload to npm
- Run
sudo npm update -g awe
to upgrade Awe on your own machine(s)
Alberon Note
Remember to upgrade Awe on Jericho.