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>