20885: Add our own pdoc wrapper
[arvados.git] / 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 you must activate the virtualenv (e.g., run @. .venv/bin/activate@) before you run the @bundle exec rake@ commands below.
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>