1 ###. Copyright (C) The Arvados Authors. All rights reserved.
3 .... SPDX-License-Identifier: CC-BY-SA-3.0
5 h1. Arvados documentation
7 This is the source code for "doc.arvados.org":http://doc.arvados.org.
9 Here's how to build the HTML pages locally so you can preview your updates before you commit and push.
11 Additional information is available on the "'Documentation' page on the Arvados wiki":https://dev.arvados.org/projects/arvados/wiki/Documentation.
13 h2. Install dependencies
15 To build the core Arvados documentation:
18 arvados/doc$ sudo apt-get install build-essential libcurl4-openssl-dev libgnutls28-dev libssl-dev
19 arvados/doc$ bundle install
22 SDK reference documentation has additional, optional build requirements.
24 h3. Java SDK documentation
27 $ sudo apt install gradle
30 h3. Python SDK documentation
33 arvados/doc$ sudo apt install python3-venv
34 arvados/doc$ python3 -m venv .venv
35 arvados/doc$ .venv/bin/pip install pdoc setuptools
38 Then you must activate the virtualenv (e.g., run @. .venv/bin/activate@) before you run the @bundle exec rake@ commands below.
40 h3. R SDK documentation
43 $ sudo apt install r-cran-devtools r-cran-roxygen2 r-cran-knitr r-cran-markdown r-cran-xml
46 h2. Generate HTML pages
49 arvados/doc$ bundle exec rake
52 Alternately, to make the documentation browsable on the local filesystem:
55 arvados/doc$ bundle exec rake generate baseurl=$PWD/.site
60 If you have "Linkchecker":http://wummel.github.io/linkchecker/ installed on
61 your system, you can run it against the documentation:
64 arvados/doc$ bundle exec rake linkchecker baseurl=file://$PWD/.site
67 Please note that this will regenerate your $PWD/.site directory.
69 h2. Preview HTML pages
72 arvados/doc$ bundle exec rake run
73 [2014-03-10 09:03:41] INFO WEBrick 1.3.1
74 [2014-03-10 09:03:41] INFO ruby 2.1.1 (2014-02-24) [x86_64-linux]
75 [2014-03-10 09:03:41] INFO WEBrick::HTTPServer#start: pid=8926 port=8000
78 Preview the rendered pages at "http://localhost:8000":http://localhost:8000.
80 h2. Publish HTML pages inside Workbench
82 (or some other web site)
84 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@:
87 arvados/doc$ bundle exec rake generate baseurl=/doc arvados_api_host=xyzzy.arvadosapi.com
90 h2. Delete generated files
93 arvados/doc$ bundle exec rake realclean