3504: Don't create stand-in "name" links for post #3036 apiserver
[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://arvados.org/projects/arvados/wiki/Documentation.
8
9 h2. Install dependencies
10
11 <pre>
12 arvados/doc$ bundle install
13 </pre>
14
15 h2. Generate HTML pages
16
17 <pre>
18 arvados/doc$ rake
19 </pre>
20
21 Alternately, to make the documentation browsable on the local filesystem:
22
23 <pre>
24 arvados/doc$ rake generate baseurl=$PWD/.site
25 </pre>
26
27 h2. Run linkchecker
28
29 If you have "Linkchecker":http://wummel.github.io/linkchecker/ installed on
30 your system, you can run it against the documentation:
31
32 <pre>
33 arvados/doc$ rake linkchecker baseurl=file://$PWD/.site
34 </pre>
35
36 Please note that this will regenerate your $PWD/.site directory.
37
38 h2. Preview HTML pages
39
40 <pre>
41 arvados/doc$ rake run
42 [2014-03-10 09:03:41] INFO  WEBrick 1.3.1
43 [2014-03-10 09:03:41] INFO  ruby 2.1.1 (2014-02-24) [x86_64-linux]
44 [2014-03-10 09:03:41] INFO  WEBrick::HTTPServer#start: pid=8926 port=8000
45 </pre>
46
47 Preview the rendered pages at "http://localhost:8000":http://localhost:8000.
48
49 h2. Publish HTML pages inside Workbench
50
51 (or some other web site)
52
53 You can set @baseurl@ (the URL prefix for all internal links), @arvados_api_host@ and @arvados_workbench_host@ without changing @_config.yml@:
54
55 <pre>
56 arvados/doc$ rake generate baseurl=/doc arvados_api_host=xyzzy.arvadosapi.com
57 </pre>
58
59 Make the docs appear at {workbench_host}/doc by creating a symbolic link in Workbench's @public@ directory, pointing to the generated HTML tree.
60
61 <pre>
62 arvados/doc$ ln -sn ../../../doc/.site ../apps/workbench/public/doc
63 </pre>
64
65 h2. Delete generated files
66
67 <pre>
68 arvados/doc$ rake realclean
69 </pre>