Aquarium Development Guide
These guidelines are intended for those working directly on Aquarium, though some details are shared with protocol development.
- Aquarium Development Guide
Follow the Aquarium installation instructions to get a local copy of the Aquarium git repository.
As explained in the installation instructions, you can run Aquarium with
and stop it with
As you work on Aquarium, you will want to run commands that need the Aquarium Ruby environment (e.g.,
To avoid having to do the manual installation steps, you can simply precede each command with
docker-compose run -rm web
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
Here are some (borrowed) style guidelines for documentation:
- Write your comments to be read from the source file. So, add formatting that is helpful to the programmer reading your code.
- The first sentence of the should be short, clear and to the point. Use the third person, e.g., “Returns the item ID for…”
- If documenting a class, use “this” to refer to an instance of the class.
- Aim for one (short) sentence per line. Each should end with a period.
@paramfor all parameters,
@returnfor return values, and
@raisefor exceptions raised. List these in that order.
- Put a single blank line after the first sentence, and then one after each paragraph.
(If this doesn’t give you a line before the first
@raiseas a phrase starting with a lowercase letter and almost always the word “the”, but with no period.
@raiseas a conditional phrase beginning with “if”. Again, don’t end the phrase with a period.
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
But, there are many more tags available, and you should feel free to use them.
Running the command
will generate the documentation and write it to the directory
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/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
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.
klavingslab.org/aquarium/protocol_developer/table/ maps to the file
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
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.
/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
- (make sure Rails tests pass)
- Run rubocop, fix anything broken. Once done run
- Update API by running
- (make sure JS tests pass)
- Make sure JS linting passes
- Update change log