Project

General

Profile

Documentation project » History » Version 41

Ward Vandewege, 03/29/2021 08:36 PM
Update instructions for generating the docs locally, cf. changes in #17245

1 32 Ward Vandewege
h1. Documentation project
2 1 Anonymous
3 34 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. It is also included in the Arvados source tree.
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 40 Tom Clegg
# Fork the arvados repository on github
45
# Clone the repository and set up the preprocessor
46
#* <pre><code>git clone git://github.com/<b>your_github_username</b>/arvados.git
47 1 Anonymous
cd arvados/doc
48
bundle install
49 40 Tom Clegg
</code></pre>
50 41 Ward Vandewege
# Generate html (it will appear in @.site/@) and view your local copy
51
#* <pre><code>rake && sensible-browser .site/index.html
52 40 Tom Clegg
</code></pre>
53 28 Nancy Ouyang
54 27 Tom Clegg
To generate Python SDK docs, install @epydoc@ and @arvados-python-client@ before running @rake@ in @arvados/doc@:
55 1 Anonymous
56 27 Tom Clegg
<pre><code>sudo apt-get install python-pip python-virtualenv
57
virtualenv /tmp/z
58 40 Tom Clegg
source /tmp/z/bin/activate
59 1 Anonymous
pip install epydoc arvados-python-client
60
rake
61
</code></pre>
62
63
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*.
64
65
Then,
66 40 Tom Clegg
# Fork the arvados repository on github
67
# Make a feature branch
68
# <pre><code>git checkout -b 4926-some-description</code></pre>
69
# Make your changes to the documentation
70
# Preview your changes with @git status@, @git diff@, etc.
71
# Add and commit the files you want to include in the update. For example:
72
# <pre><code>git add _config.yml _includes/_navbar_top.liquid _layouts/default.html.liquid index.html.liquid
73 35 Nancy Ouyang
git commit -m "4926: Added foobar to barfoo"
74
</code></pre>
75 40 Tom Clegg
# Push the branch to your github account
76
<pre><code>git push git@github.com:<b>your_github_username</b>/arvados.git 4926-getting-started:4926-getting-started
77
</code></pre>
78
# Go to https://github.com and create a pull request
79 35 Nancy Ouyang
80 40 Tom Clegg
We like to see commit messages that start with an issue number (if applicable) and describe what the new code _does_, like this:
81
* "1234: Explain it's important to install foo before baz."
82
* "1234: Update foo example to use new bar feature."
83 1 Anonymous
84 40 Tom Clegg
Less-good messages:
85
* "Improve docs."
86
* "Incorporate review feedback."
87 37 Nancy Ouyang
88 38 Nancy Ouyang
h3. Code Review
89 39 Nancy Ouyang
90 40 Tom Clegg
Next, get it reviewed and merged!
91 37 Nancy Ouyang
92 40 Tom Clegg
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:
93
* visit our IRC channel
94
* send email to support@curoverse.com
95
* Visit our "redmine issue tracker":http://arvados.org 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.
96 35 Nancy Ouyang
97 28 Nancy Ouyang
h3. Important files and folders
98
99
These are located in the arvados/doc directory.
100
101 29 Nancy Ouyang
* */css/*
102
By convention, we store all the CSS files here.
103
* */js/*
104
By convention, we store all the Javascript files here.
105
* */_includes/_navbar_top.liquid*
106
These describe the top navigation bar, if you are adding or renaming sections
107
* */_config.yml*
108
This file describes the order of pages in the left navigation bar.
109
* */_layouts/default.html.liquid*
110
If you wish to include new CSS or Javascript files (for instance, in /css or /js) across the whole site, do so here.