Documentation project¶

The documentation project is a part of the overall Arvados project. The output from this project forms the official documentation at http://doc.arvados.org. It is also included in the Arvados source tree.

As a general organizing principle, we follow https://diataxis.fr/

Guides¶

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

• Getting Started - Quickstart and overview of Arvados (what it is, who it's for, and key features).

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

• SDK Reference - Details about the accessing Arvados from various programming languages.

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

If you'd like to fix documentation bugs yourself, or to otherwise 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:

1. Fork the arvados repository on github
2. Clone the repository and set up the preprocessor

   • git clone git://github.com/<b>your_github_username</b>/arvados.git
     cd arvados/doc
     bundle install
     

3. Generate html (it will appear in .site/) and view your local copy

   • rake && sensible-browser .site/index.html
     

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
source /tmp/z/bin/activate
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 documentation purposes, https://arvados.org/issues/4926 is a safe bet. Note the issue number: 4926.

Then,

1. Fork the arvados repository on github
2. Make a feature branch

3. git checkout -b 4926-some-description

4. Make your changes to the documentation
5. Preview your changes with git status, git diff, etc.
6. Add and commit the files you want to include in the update. For example:

7. git add _config.yml _includes/_navbar_top.liquid _layouts/default.html.liquid index.html.liquid
   git commit -m "4926: Added foobar to barfoo" 
   

8. Push the branch to your github account
   

   git push git@github.com:<b>your_github_username</b>/arvados.git 4926-getting-started:4926-getting-started
   

9. Go to https://github.com and create a pull request

We like to see commit messages that start with an issue number (if applicable) and describe what the new code does, like this:

• "1234: Explain it's important to install foo before baz."
• "1234: Update foo example to use new bar feature."

Less-good messages:

• "Improve docs."
• "Incorporate review feedback."

Code Review¶

Next, get it reviewed and merged!

We should get notified when new PRs arrive, but if you'd like to move things along faster we'll be happy to hear from you one or more of the following ways:

• visit our IRC channel
• send email to support@curoverse.com
• Visit our redmine issue tracker and add a review subtask under the appropriate issue, if applicable -- just enter the subject "review 4926-some-description" and we'll know what it means.

Important files and folders¶

These are located in the arvados/doc directory.

• /css/
  By convention, we store all the CSS files here.
• /js/
  By convention, we store all the Javascript files here.
• /_includes/_navbar_top.liquid
  These describe the top navigation bar, if you are adding or renaming sections
• /_config.yml
  This file describes the order of pages in the left navigation bar.
• /_layouts/default.html.liquid
  If you wish to include new CSS or Javascript files (for instance, in /css or /js) across the whole site, do so here.