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