Documentation¶

The documentation project is a part of the overall Arvados effort.

Guides¶

There are four guides that are being developed to support the use of Arvados:

• User Guide - Introductory and tutorial materials for building analysis or web applications using Arvados.

• API Reference - REST API methods and resources, the MapReduce job execution environment, permission model, etc.

• Admin Guide - Instructions to system administrators for maintaining an Arvados installation.

• Install Guide - How to install and configure Arvados on the cloud management platform of your choice.

A web version of the documentation is available at http://doc.arvados.org.

Documentation Project¶

The Arvados documentation is written in Markdown, Textile, and HTML. The source code is in the doc directory in the Arvados source tree. We use Jekyll to render HTML pages.

Contributing¶

Bugs in the documentation can be submitted as issues.

To contribute to the documentation, clone the Arvados source repository, edit, and send pull requests just as you would when contributing program source code.

We do not yet maintain a separate documentation mailing list, so we encourage documentation contributors to join the main developer mailing list.

References for contributors:

• Markdown syntax
• Textile syntax
• Zenweb
• Liquid for designers (template engine)

Contributor quick-start:

git clone git://github.com/curoverse/arvados.git
cd arvados/doc
bundle install
rake
# documentation will be generated in .site/
rake run

Note: The repository is only a few megabytes in size.
You can now preview it in your browser at http://localhost:8000 .

To generate Python SDK docs, install epydoc and arvados-python-client before running rake in arvados/doc:

sudo apt-get install python-pip python-virtualenv
virtualenv /tmp/z
PATH=/tmp/z/bin:$PATH
pip install epydoc arvados-python-client
rake

When you want to start making changes to the site, do so on a branch. If you'd like to follow our development process, create or pick an existing issue, for instance https://arvados.org/issues/4926. Note the issue number: 4926.

Then,

git checkout -b 4926-some-description
# (make your changes to the documentation)
git status #shows you what files have chnaged
# Next, git add [the files you want to include in the update]
git add _config.yml _includes/_navbar_top.liquid _layouts/default.html.liquid index.html.liquid
git commit -m "4926: Added foobar to barfoo" 
git remote add curoverse git@git.curoverse.com:arvados.git
git push curoverse 4926-getting-started:4926-getting-started

The last command will throw “fatal” error if you’re pushing a new branch, e.g. “remote: fatal: Invalid revision range". Additionally, if you get a 403 error, email support@curoverse.com to request write permissions on the Arvados repository.

Code Review¶

Next, get it reviewed! After logging in to Arvados Redmine (http://arvados.org), add it as a task under the appropriate story on the Arvados storyboard.

https://arvados.org/rb/taskboards/83

If you don't see a green + sign on the stories in the Story column, like below,

email support@curoverse.com to get permissions in the Redmine issue tracker to add tasks.

Call it something along the lines of "Review branch: 4926-some-description".

It should get reviewed shortly, if not email support@curoverse.com .

Important files and folders¶

These are located in the arvados/doc directory.

• /css/
• /js/
• /_includes/_navbar_top.liquid &_navbar_left.liquid
• /_config.yml (declare navigation / order of pages)
• /_layouts/default.html.liquid (declare CSS, javascript includes)