Arvados

h1. Documentation

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

h2. Guides

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

* "User Guide":http://doc.arvados.org/user/ - Introductory and tutorial materials for building analysis or web applications using Arvados. 

* "API Reference":http://doc.arvados.org/api/ - REST API methods and resources, the MapReduce job execution environment, permission model, etc.

* "Admin Guide":http://doc.arvados.org/admin/ - Instructions to system administrators for maintaining an Arvados installation.

* "Install Guide":http://doc.arvados.org/install/ - 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. 

h2. 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.

h2. Contributing

Bugs in the documentation can be submitted as "issues":/projects/arvados/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":http://daringfireball.net/projects/markdown/syntax

* "Textile syntax":http://redcloth.org/textile

* "Zenweb":http://www.zenspider.com/projects/zenweb.html

* "Liquid for designers":https://github.com/shopify/liquid/wiki/liquid-for-designers (template engine)

Contributor quick-start:

<pre><code>git clone git://github.com/curoverse/arvados.git

cd arvados/doc

bundle install

rake

# documentation will be generated in .site/

rake run

</code></pre>

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@:

<pre><code>sudo apt-get install python-pip python-virtualenv

virtualenv /tmp/z

PATH=/tmp/z/bin:$PATH

pip install epydoc arvados-python-client

rake

</code></pre>

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,

<pre><code>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

</code></pre>

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.

h3. 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,

!greenbutton.png!

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 .

h3. 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)