Project

General

Profile

Documentation project » History » Revision 31

Revision 30 (Nancy Ouyang, 01/22/2015 07:40 PM) → Revision 31/42 (Nancy Ouyang, 01/22/2015 08:57 PM)

h1. Documentation 

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

 h2. Guides 

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

 * "Getting Started":http://doc.arvados.org/start/ - Quickstart and overview of Arvados (what it is, who it's for, and key features). 

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

 * "SDK Reference":http://doc.arvados.org/sdk/ - Details about the accessing Arvados from various programming languages. 

 * "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.  

 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":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 documentation purposes, https://arvados.org/issues/4926 is a safe bet. 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 changed 
 # Next, git add [the files you want to include in the update. For example...] 
 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". This can be safely ignored. 

 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 subtask task under the appropriate issue. story on the Arvados storyboard. Story/issue 4926 is a safe bet. 

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

 If you don't see and "Add" link a green "+" sign (shown below) on the subtasks on stories in the issue Story column 

 !subtask.png! !greenbutton.png! 

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

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

 The task / branch should get reviewed shortly. If not, email support@curoverse.com . 

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