Project

General

Profile

Documentation project » History » Version 33

Ward Vandewege, 02/02/2015 08:05 PM

1 32 Ward Vandewege
h1. Documentation project
2 1 Anonymous
3 33 Ward Vandewege
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":http://doc.arvados.org
4 1 Anonymous
5
h2. Guides
6
7 29 Nancy Ouyang
There are six guides that are being developed to support the use of Arvados: 
8 1 Anonymous
9 29 Nancy Ouyang
* "Getting Started":http://doc.arvados.org/start/ - Quickstart and overview of Arvados (what it is, who it's for, and key features).
10 1 Anonymous
11
* "User Guide":http://doc.arvados.org/user/ - Introductory and tutorial materials for building analysis or web applications using Arvados.
12 30 Nancy Ouyang
13
* "SDK Reference":http://doc.arvados.org/sdk/ - Details about the accessing Arvados from various programming languages.
14 29 Nancy Ouyang
15 1 Anonymous
* "API Reference":http://doc.arvados.org/api/ - REST API methods and resources, the MapReduce job execution environment, permission model, etc.
16
17 14 Anonymous
* "Admin Guide":http://doc.arvados.org/admin/ - Instructions to system administrators for maintaining an Arvados installation.
18 12 Anonymous
19 29 Nancy Ouyang
* "Install Guide":http://doc.arvados.org/install/ - How to install and configure Arvados on the cloud management platform of your choice.
20 15 Anonymous
21 29 Nancy Ouyang
A web version of the documentation is available at http://doc.arvados.org.
22 6 Tom Clegg
23 1 Anonymous
h2. Documentation Project
24
25 7 Tom Clegg
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.
26 1 Anonymous
27 7 Tom Clegg
h2. Contributing
28 1 Anonymous
29 29 Nancy Ouyang
Bugs in the documentation can be submitted as "issues":/projects/arvados/issues. 
30 6 Tom Clegg
31 29 Nancy Ouyang
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.
32 6 Tom Clegg
33
We do not yet maintain a separate documentation mailing list, so we encourage documentation contributors to join the main developer mailing list.
34
35
References for contributors:
36
37
* "Markdown syntax":http://daringfireball.net/projects/markdown/syntax
38 25 Peter Amstutz
* "Textile syntax":http://redcloth.org/textile
39
* "Zenweb":http://www.zenspider.com/projects/zenweb.html
40 6 Tom Clegg
* "Liquid for designers":https://github.com/shopify/liquid/wiki/liquid-for-designers (template engine)
41 11 Tom Clegg
42
Contributor quick-start:
43 1 Anonymous
44 26 Peter Amstutz
<pre><code>git clone git://github.com/curoverse/arvados.git
45 11 Tom Clegg
cd arvados/doc
46 25 Peter Amstutz
bundle install
47
rake
48
# documentation will be generated in .site/
49 28 Nancy Ouyang
rake run
50 25 Peter Amstutz
</code></pre>
51 28 Nancy Ouyang
Note: The repository is only a few megabytes in size.
52
You can now preview it in your browser at http://localhost:8000 .
53 27 Tom Clegg
54 28 Nancy Ouyang
55 27 Tom Clegg
To generate Python SDK docs, install @epydoc@ and @arvados-python-client@ before running @rake@ in @arvados/doc@:
56 1 Anonymous
57 27 Tom Clegg
<pre><code>sudo apt-get install python-pip python-virtualenv
58
virtualenv /tmp/z
59
PATH=/tmp/z/bin:$PATH
60 1 Anonymous
pip install epydoc arvados-python-client
61
rake
62 27 Tom Clegg
</code></pre>
63 28 Nancy Ouyang
64 29 Nancy Ouyang
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*.
65 28 Nancy Ouyang
66
Then,
67 1 Anonymous
68 28 Nancy Ouyang
<pre><code>git checkout -b 4926-some-description
69 1 Anonymous
# (make your changes to the documentation)
70 29 Nancy Ouyang
git status # shows you what files have changed
71
# Next, git add [the files you want to include in the update. For example...]
72 1 Anonymous
git add _config.yml _includes/_navbar_top.liquid _layouts/default.html.liquid index.html.liquid
73 28 Nancy Ouyang
git commit -m "4926: Added foobar to barfoo"
74
git remote add curoverse git@git.curoverse.com:arvados.git
75 1 Anonymous
git push curoverse 4926-getting-started:4926-getting-started
76 28 Nancy Ouyang
</code></pre>
77
78 29 Nancy Ouyang
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.
79 28 Nancy Ouyang
80 29 Nancy Ouyang
Additionally, if you get a 403 error, email support@curoverse.com to request write permissions on the Arvados repository.
81
82 28 Nancy Ouyang
h3. Code Review
83 1 Anonymous
84 31 Nancy Ouyang
Next, get it reviewed! After logging in to Arvados Redmine (http://arvados.org), add it as a subtask under the appropriate issue. Story/issue 4926 is a safe bet.
85 1 Anonymous
86 31 Nancy Ouyang
https://arvados.org/issues/4926
87 1 Anonymous
88 31 Nancy Ouyang
If you don't see and "Add" link (shown below) on the subtasks on the issue
89 1 Anonymous
90 31 Nancy Ouyang
!subtask.png!
91 1 Anonymous
92 28 Nancy Ouyang
email support@curoverse.com to get permissions in the Redmine issue tracker to add tasks.
93
94 29 Nancy Ouyang
Call the task something along the lines of "Review branch: 4926-some-description".
95 28 Nancy Ouyang
96 29 Nancy Ouyang
The task / branch should get reviewed shortly. If not, email support@curoverse.com .
97 28 Nancy Ouyang
98
h3. Important files and folders
99
100
These are located in the arvados/doc directory.
101
102 29 Nancy Ouyang
* */css/*
103
By convention, we store all the CSS files here.
104
* */js/*
105
By convention, we store all the Javascript files here.
106
* */_includes/_navbar_top.liquid*
107
These describe the top navigation bar, if you are adding or renaming sections
108
* */_config.yml*
109
This file describes the order of pages in the left navigation bar.
110
* */_layouts/default.html.liquid*
111
If you wish to include new CSS or Javascript files (for instance, in /css or /js) across the whole site, do so here.