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