doc/README.textile

   1 h1. Arvados documentation
   2
   3 This is the source code for "doc.arvados.org":http://doc.arvados.org.
   4
   5 Here's how to build the HTML pages locally so you can preview your updates before you commit and push.
   6
   7 Additional information is available on the "'Documentation' page on the Arvados wiki":https://arvados.org/projects/arvados/wiki/Documentation.
   8
   9 h2. 0. Install dependencies
  10
  11 <pre>
  12 arvados/doc$ bundle install
  13 </pre>
  14
  15 h2. 1. Generate HTML pages
  16
  17 <pre>
  18 arvados/doc$ rake
  19 </pre>
  20
  21 Alternately, to make the documentation browsable on the local filesystem:
  22
  23 <pre>
  24 arvados/doc$ rake generate baseurl=$PWD/.site
  25 </pre>
  26
  27 h2. 2. Preview HTML pages
  28
  29 <pre>
  30 arvados/doc$ rake run
  31 [2014-03-10 09:03:41] INFO  WEBrick 1.3.1
  32 [2014-03-10 09:03:41] INFO  ruby 2.1.1 (2014-02-24) [x86_64-linux]
  33 [2014-03-10 09:03:41] INFO  WEBrick::HTTPServer#start: pid=8926 port=8000
  34 </pre>
  35
  36 Preview the rendered pages at "http://localhost:8000":http://localhost:8000.
  37
  38 h2. 3. Publish HTML pages inside Workbench
  39
  40 (or some other web site)
  41
  42 You can set @baseurl@ (the URL prefix for all internal links), @arvados_api_host@ and @arvados_workbench_host@ without changing @_config.yml@:
  43
  44 <pre>
  45 arvados/doc$ rake generate baseurl=/doc arvados_api_host=xyzzy.arvadosapi.com
  46 </pre>
  47
  48 Make the docs appear at {workbench_host}/doc by creating a symbolic link in Workbench's @public@ directory, pointing to the generated HTML tree.
  49
  50 <pre>
  51 arvados/doc$ ln -sn ../../../doc/.site ../apps/workbench/public/doc
  52 </pre>
  53
  54 h2. 4. Delete generated files
  55
  56 <pre>
  57 arvados/doc$ rake realclean
  58 </pre>