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