21494: Let documentation build specify what SDKs should be included
[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 To build the core Arvados documentation:
16
17 <pre>
18 arvados/doc$ sudo apt-get install build-essential libcurl4-openssl-dev libgnutls28-dev libssl-dev
19 arvados/doc$ bundle install
20 </pre>
21
22 SDK reference documentation has additional, optional build requirements.
23
24 h3. Java SDK documentation
25
26 <pre>
27 $ sudo apt install gradle
28 </pre>
29
30 h3. Python SDK documentation
31
32 <pre>
33 arvados/doc$ sudo apt install python3-venv
34 arvados/doc$ python3 -m venv .venv
35 arvados/doc$ .venv/bin/pip install pdoc setuptools
36 </pre>
37
38 Then you must activate the virtualenv (e.g., run @. .venv/bin/activate@) before you run the @bundle exec rake@ commands below.
39
40 h3. R SDK documentation
41
42 <pre>
43 $ sudo apt install r-cran-devtools r-cran-roxygen2 r-cran-knitr r-cran-markdown r-cran-xml
44 </pre>
45
46 h2. Generate HTML pages
47
48 <pre>
49 arvados/doc$ bundle exec rake
50 </pre>
51
52 Alternately, to make the documentation browsable on the local filesystem:
53
54 <pre>
55 arvados/doc$ bundle exec rake generate baseurl=$PWD/.site
56 </pre>
57
58 h3. Selecting SDK documentation to build
59
60 By default, the build process will try to detect what SDK documentation it can build, build all that, and skip the rest. You can specify exactly what you want to build using the @sdks@ environment variable. This is a list of comma- or space-separated SDKs you wanted to build documentation for. Valid values are @java@, @python@, @r@, @all@, or @none@. @all@ is a shortcut for listing all the valid SDKs. @none@ means do not build documentation for any SDK. For example, to build documentation for the Java and Python SDKs, but skip R:
61
62 <pre>
63 arvados/doc$ bundle exec rake generate baseurl=$PWD/.site sdks=java,python
64 </pre>
65
66 Specifying @sdks@ skips the build detection logic. If the Rakefile cannot build the requested SDK documentation, the build will fail.
67
68 For backwards compatibility, if you do not specify @sdks@, but the @NO_SDK@ environment variable is set, or the @no-sdk@ file exists, the build will run as if you set @sdks=none@.
69
70 h2. Run linkchecker
71
72 If you have "Linkchecker":http://wummel.github.io/linkchecker/ installed on
73 your system, you can run it against the documentation:
74
75 <pre>
76 arvados/doc$ bundle exec rake linkchecker baseurl=file://$PWD/.site
77 </pre>
78
79 Please note that this will regenerate your $PWD/.site directory.
80
81 h2. Preview HTML pages
82
83 <pre>
84 arvados/doc$ bundle exec rake run
85 [2014-03-10 09:03:41] INFO  WEBrick 1.3.1
86 [2014-03-10 09:03:41] INFO  ruby 2.1.1 (2014-02-24) [x86_64-linux]
87 [2014-03-10 09:03:41] INFO  WEBrick::HTTPServer#start: pid=8926 port=8000
88 </pre>
89
90 Preview the rendered pages at "http://localhost:8000":http://localhost:8000.
91
92 h2. Publish HTML pages inside Workbench
93
94 (or some other web site)
95
96 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@:
97
98 <pre>
99 arvados/doc$ bundle exec rake generate baseurl=/doc arvados_api_host=xyzzy.arvadosapi.com
100 </pre>
101
102 h2. Delete generated files
103
104 <pre>
105 arvados/doc$ bundle exec rake realclean
106 </pre>