Merge branch 'master' into 10979-cancelled-job-nodes
[arvados.git] / doc / README.textile
1 h1. Arvados documentation
2
3 This is the source code for "doc.arvados.org":http://doc.arvados.org.
4
5 Here's how to build the HTML pages locally so you can preview your updates before you commit and push.
6
7 Additional information is available on the "'Documentation' page on the Arvados wiki":https://dev.arvados.org/projects/arvados/wiki/Documentation.
8
9 h2. Install dependencies
10
11 <pre>
12 arvados/doc$ bundle install
13 arvados/doc$ pip install epydoc
14 </pre>
15
16 h2. Generate HTML pages
17
18 <pre>
19 arvados/doc$ rake
20 </pre>
21
22 Alternately, to make the documentation browsable on the local filesystem:
23
24 <pre>
25 arvados/doc$ rake generate baseurl=$PWD/.site
26 </pre>
27
28 h2. Run linkchecker
29
30 If you have "Linkchecker":http://wummel.github.io/linkchecker/ installed on
31 your system, you can run it against the documentation:
32
33 <pre>
34 arvados/doc$ rake linkchecker baseurl=file://$PWD/.site
35 </pre>
36
37 Please note that this will regenerate your $PWD/.site directory.
38
39 h2. Preview HTML pages
40
41 <pre>
42 arvados/doc$ rake run
43 [2014-03-10 09:03:41] INFO  WEBrick 1.3.1
44 [2014-03-10 09:03:41] INFO  ruby 2.1.1 (2014-02-24) [x86_64-linux]
45 [2014-03-10 09:03:41] INFO  WEBrick::HTTPServer#start: pid=8926 port=8000
46 </pre>
47
48 Preview the rendered pages at "http://localhost:8000":http://localhost:8000.
49
50 h2. Publish HTML pages inside Workbench
51
52 (or some other web site)
53
54 You can set @baseurl@ (the URL prefix for all internal links), @arvados_api_host@ and @arvados_workbench_host@ without changing @_config.yml@:
55
56 <pre>
57 arvados/doc$ rake generate baseurl=/doc arvados_api_host=xyzzy.arvadosapi.com
58 </pre>
59
60 Make the docs appear at {workbench_host}/doc by creating a symbolic link in Workbench's @public@ directory, pointing to the generated HTML tree.
61
62 <pre>
63 arvados/doc$ ln -sn ../../../doc/.site ../apps/workbench/public/doc
64 </pre>
65
66 h2. Delete generated files
67
68 <pre>
69 arvados/doc$ rake realclean
70 </pre>