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 h2. Run linkchecker
  59
  60 If you have "Linkchecker":http://wummel.github.io/linkchecker/ installed on
  61 your system, you can run it against the documentation:
  62
  63 <pre>
  64 arvados/doc$ bundle exec rake linkchecker baseurl=file://$PWD/.site
  65 </pre>
  66
  67 Please note that this will regenerate your $PWD/.site directory.
  68
  69 h2. Preview HTML pages
  70
  71 <pre>
  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
  76 </pre>
  77
  78 Preview the rendered pages at "http://localhost:8000":http://localhost:8000.
  79
  80 h2. Publish HTML pages inside Workbench
  81
  82 (or some other web site)
  83
  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@:
  85
  86 <pre>
  87 arvados/doc$ bundle exec rake generate baseurl=/doc arvados_api_host=xyzzy.arvadosapi.com
  88 </pre>
  89
  90 h2. Delete generated files
  91
  92 <pre>
  93 arvados/doc$ bundle exec rake realclean
  94 </pre>