Merge branch '16791-api-flaky-test-fix'
[arvados.git] / doc / README.textile
1 ###. Copyright (C) The Arvados Authors. All rights reserved.
2 ....
3 .... SPDX-License-Identifier: CC-BY-SA-3.0
4
5 h1. Arvados documentation
6
7 This is the source code for "doc.arvados.org":http://doc.arvados.org.
8
9 Here's how to build the HTML pages locally so you can preview your updates before you commit and push.
10
11 Additional information is available on the "'Documentation' page on the Arvados wiki":https://dev.arvados.org/projects/arvados/wiki/Documentation.
12
13 h2. Install dependencies
14
15 <pre>
16 arvados/doc$ sudo apt-get install build-essential libcurl4-openssl-dev libgnutls28-dev libssl-dev
17 arvados/doc$ bundle install
18 </pre>
19
20 To generate the Python SDK documentation, these additional dependencies are needed:
21
22 <pre>
23 arvados/doc$ sudo apt-get install python3-pip
24 arvados/doc$ pip3 install arvados-python-client
25 arvados/doc$ pip3 install pdoc3
26 </pre>
27
28 h2. Generate HTML pages
29
30 <pre>
31 arvados/doc$ bundle exec rake
32 </pre>
33
34 Alternately, to make the documentation browsable on the local filesystem:
35
36 <pre>
37 arvados/doc$ bundle exec rake generate baseurl=$PWD/.site
38 </pre>
39
40 h2. Run linkchecker
41
42 If you have "Linkchecker":http://wummel.github.io/linkchecker/ installed on
43 your system, you can run it against the documentation:
44
45 <pre>
46 arvados/doc$ bundle exec rake linkchecker baseurl=file://$PWD/.site
47 </pre>
48
49 Please note that this will regenerate your $PWD/.site directory.
50
51 h2. Preview HTML pages
52
53 <pre>
54 arvados/doc$ bundle exec rake run
55 [2014-03-10 09:03:41] INFO  WEBrick 1.3.1
56 [2014-03-10 09:03:41] INFO  ruby 2.1.1 (2014-02-24) [x86_64-linux]
57 [2014-03-10 09:03:41] INFO  WEBrick::HTTPServer#start: pid=8926 port=8000
58 </pre>
59
60 Preview the rendered pages at "http://localhost:8000":http://localhost:8000.
61
62 h2. Publish HTML pages inside Workbench
63
64 (or some other web site)
65
66 You can set @baseurl@ (the URL prefix for all internal links), @arvados_cluster_uuid@, @arvados_api_host@ and @arvados_workbench_host@ without changing @_config.yml@:
67
68 <pre>
69 arvados/doc$ bundle exec rake generate baseurl=/doc arvados_api_host=xyzzy.arvadosapi.com
70 </pre>
71
72 Make the docs appear at {workbench_host}/doc by creating a symbolic link in Workbench's @public@ directory, pointing to the generated HTML tree.
73
74 <pre>
75 arvados/doc$ ln -sn ../../../doc/.site ../apps/workbench/public/doc
76 </pre>
77
78 h2. Delete generated files
79
80 <pre>
81 arvados/doc$ bundle exec rake realclean
82 </pre>