Aquarium / Aquarium development

Aquarium Development Guide

These guidelines are intended for those working directly on Aquarium, though some details are shared with protocol development.


Getting Started

Follow the Aquarium installation instructions to get a local copy of the Aquarium git repository.

Running Aquarium

As explained in the installation instructions, you can run Aquarium with

docker-compose up

and stop it with

docker-compose down

As you work on Aquarium, you will want to run commands that need the Aquarium Ruby environment (e.g., rails commands). To avoid having to do the manual installation steps, you can simply precede each command with

docker-compose run -rm web

Testing Aquarium

Editing Aquarium

Documenting changes

Formatting Aquarium code

Documenting Aquarium Ruby Code

Aquarium Ruby methods and classes should be documented with Yardoc regardless of whether they are public.

For instance, a function would be documented as

# Display the instructions for centerfuging the given tubes.
#
# @param tubes [Array] the array of items representing tubes
def centerfuge_instructions(tubes)
  ...
end

unless a hash argument is used, in which case the comment would look like

# Copy the data associations from the source item to the target item.
#
# @param args [Hash] the arguments indicating source and target items
# @option args [String] :source  the source item
# @option args [String] :target  the target item
def copy_associations(args)
  ...
end

Note that an argument with a default value is not an option, and should just be listed using the @param tag.

Here are some (borrowed) style guidelines for documentation:

See also these yard examples

The return value of a function should be documented using the @return tag, and any exception raised by a function should be documented with the @raise tag. But, there are many more tags available, and you should feel free to use them.

Running the command

yardoc

will generate the documentation and write it to the directory docs/api. This location is determined by the file .yardopts in the project repository. This file also limits the API to code used in Krill the protocol development language.

Modifying the Site

The Aquarium project pages settings display the files in the docs directory of the master branch as the project site http://klavinslab.org/aquarium.

The site is built from the kramdown flavor of Markdown using GitHub flavored Jekyll. It riffs off of the Cayman theme, set through the project pages settings for the Aquarium project. The files in docs/_layouts, docs/_includes, docs/_sass, and docs/assets/css define changes that override the theme defaults.

The content of the site is located in the files in docs/_docs with each subdirectory having a index.md file that is loaded when the directory name is used (e.g., klavinslab.org/aquarium/manager maps to the file docs/_docs/manager/index.md). These Markdown files have a permalink that determines this mapping. Because of the way that general permalinks are defined in docs/_config.yml, other markdown documents correspond to a URL with the file name. For instance, klavingslab.org/aquarium/protocol_developer/table/ maps to the file docs/_docs/protocol_developer/table.md.

To avoid issues creating links using standard Markdown hyperlinks, use the Liquid link tag that will do the mapping from the file path. This tag takes the absolute path relative to the docs directory, so use /installation/ to get the link for the file docs/_docs/installation/index.md. However, this link will be relative to the docs directory, and to get the complete mapping we have to add the base URL for the site. So use /aquarium/installation/ to get the correct link on the generated page. Using the link tag to reference image files in the images subdirectory for each topic will avoid discrepancies between a local preview and how the site is displayed on GitHub.

Unfortunately, images linked this way will actually not be rendered in a local preview. To see the pages rendered properly, install the github-pages gem, run jekyll serve from the docs directory, and visit localhost:4000 with a browser. For more detail, see the instructions from GitHub.

Making an Aquarium Release

this is a draft list

  1. (make sure Rails tests pass)
  2. Run rubocop, fix anything broken. Once done run rubocop --auto-gen-config.
  3. Update API by running yard
  4. (make sure JS tests pass)
  5. Make sure JS linting passes
  6. Update change log