21654: Upgrades github.com/docker/docker to address CVE-2024-24557

[arvados.git] / doc / README.textile

diff --git a/doc/README.textile b/doc/README.textile
index 9d58dfeb636481d13c842e7c7bfc5b2151d70679..84275955454c2f3f40ca7d3827539d98d84dbe69 100644 (file)
--- a/doc/README.textile
+++ b/doc/README.textile
@@ -1,36 +1,79 @@
+###. Copyright (C) The Arvados Authors. All rights reserved.
+....
+.... SPDX-License-Identifier: CC-BY-SA-3.0
+
 h1. Arvados documentation
 
 This is the source code for "doc.arvados.org":http://doc.arvados.org.
 
 Here's how to build the HTML pages locally so you can preview your updates before you commit and push.
 
-Additional information is available on the "'Documentation' page on the Arvados wiki":https://arvados.org/projects/arvados/wiki/Documentation.
+Additional information is available on the "'Documentation' page on the Arvados wiki":https://dev.arvados.org/projects/arvados/wiki/Documentation.
 
 h2. Install dependencies
 
+To build the core Arvados documentation:
+
 <pre>
+arvados/doc$ sudo apt-get install build-essential libcurl4-openssl-dev libgnutls28-dev libssl-dev
 arvados/doc$ bundle install
 </pre>
 
+SDK reference documentation has additional, optional build requirements.
+
+h3. Java SDK documentation
+
+<pre>
+$ sudo apt install gradle
+</pre>
+
+h3. Python SDK documentation
+
+<pre>
+arvados/doc$ sudo apt install python3-venv
+arvados/doc$ python3 -m venv .venv
+arvados/doc$ .venv/bin/pip install pdoc setuptools
+</pre>
+
+Then you must activate the virtualenv (e.g., run @. .venv/bin/activate@) before you run the @bundle exec rake@ commands below.
+
+h3. R SDK documentation
+
+<pre>
+$ sudo apt install r-cran-devtools r-cran-roxygen2 r-cran-knitr r-cran-markdown r-cran-xml
+</pre>
+
 h2. Generate HTML pages
 
 <pre>
-arvados/doc$ rake
+arvados/doc$ bundle exec rake
 </pre>
 
 Alternately, to make the documentation browsable on the local filesystem:
 
 <pre>
-arvados/doc$ rake generate baseurl=$PWD/.site
+arvados/doc$ bundle exec rake generate baseurl=$PWD/.site
+</pre>
+
+h3. Selecting SDK documentation to build
+
+By default, the build process will try to detect what SDK documentation it can build, build all that, and skip the rest. You can specify exactly what you want to build using the @sdks@ environment variable. This is a list of comma- or space-separated SDKs you wanted to build documentation for. Valid values are @java@, @python@, @r@, @all@, or @none@. @all@ is a shortcut for listing all the valid SDKs. @none@ means do not build documentation for any SDK. For example, to build documentation for the Java and Python SDKs, but skip R:
+
+<pre>
+arvados/doc$ bundle exec rake generate baseurl=$PWD/.site sdks=java,python
 </pre>
 
+Specifying @sdks@ skips the build detection logic. If the Rakefile cannot build the requested SDK documentation, the build will fail.
+
+For backwards compatibility, if you do not specify @sdks@, but the @NO_SDK@ environment variable is set, or the @no-sdk@ file exists, the build will run as if you set @sdks=none@.
+
 h2. Run linkchecker
 
 If you have "Linkchecker":http://wummel.github.io/linkchecker/ installed on
 your system, you can run it against the documentation:
 
 <pre>
-arvados/doc$ rake linkchecker baseurl=file://$PWD/.site
+arvados/doc$ bundle exec rake linkchecker baseurl=file://$PWD/.site
 </pre>
 
 Please note that this will regenerate your $PWD/.site directory.
@@ -38,7 +81,7 @@ Please note that this will regenerate your $PWD/.site directory.
 h2. Preview HTML pages
 
 <pre>
-arvados/doc$ rake run
+arvados/doc$ bundle exec rake run
 [2014-03-10 09:03:41] INFO  WEBrick 1.3.1
 [2014-03-10 09:03:41] INFO  ruby 2.1.1 (2014-02-24) [x86_64-linux]
 [2014-03-10 09:03:41] INFO  WEBrick::HTTPServer#start: pid=8926 port=8000
@@ -50,20 +93,14 @@ h2. Publish HTML pages inside Workbench
 
 (or some other web site)
 
-You can set @baseurl@ (the URL prefix for all internal links), @arvados_api_host@ and @arvados_workbench_host@ without changing @_config.yml@:
-
-<pre>
-arvados/doc$ rake generate baseurl=/doc arvados_api_host=xyzzy.arvadosapi.com
-</pre>
-
-Make the docs appear at {workbench_host}/doc by creating a symbolic link in Workbench's @public@ directory, pointing to the generated HTML tree.
+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@:
 
 <pre>
-arvados/doc$ ln -sn ../../../doc/.site ../apps/workbench/public/doc
+arvados/doc$ bundle exec rake generate baseurl=/doc arvados_api_host=xyzzy.arvadosapi.com
 </pre>
 
 h2. Delete generated files
 
 <pre>
-arvados/doc$ rake realclean
+arvados/doc$ bundle exec rake realclean
 </pre>