* README: remove numbers in headings

* linkchecker: only check file:// links

* epydoc: run against the local source tree, not against whatever
  version of the python 'arvados' package is installed

* generate: re-run epydoc on every generation

* generate: do not fail to include the epydoc output files if they are
  generated in the current run (which they now always are)

diff --git a/.gitignore b/.gitignore
index 4d6cc39a237559d2d2530bef984194cb456ee1cf..4fe6ac8b19ef4c2b97c8994913a403e05578895d 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -2,6 +2,5 @@
 *.pyc
 docker/*/generated/*
 docker/config.yml
-doc/_site/*
 doc/.site/*
-doc/sdk/python/arvados
\ No newline at end of file
+doc/sdk/python/arvados

diff --git a/doc/.gitignore b/doc/.gitignore
deleted file mode 100644 (file)
index ca35be0..0000000
--- a/doc/.gitignore
+++ /dev/null
@@ -1 +0,0 @@
-_site

diff --git a/doc/README.textile b/doc/README.textile
index 38a53cf7a28d20d7570be8fce9b99f1884afe0cc..9d58dfeb636481d13c842e7c7bfc5b2151d70679 100644 (file)
--- a/doc/README.textile
+++ b/doc/README.textile
@@ -6,13 +6,13 @@ Here's how to build the HTML pages locally so you can preview your updates befor
 
 Additional information is available on the "'Documentation' page on the Arvados wiki":https://arvados.org/projects/arvados/wiki/Documentation.
 
-h2. 0. Install dependencies
+h2. Install dependencies
 
 <pre>
 arvados/doc$ bundle install
 </pre>
 
-h2. 1. Generate HTML pages
+h2. Generate HTML pages
 
 <pre>
 arvados/doc$ rake
@@ -24,18 +24,18 @@ Alternately, to make the documentation browsable on the local filesystem:
 arvados/doc$ rake generate baseurl=$PWD/.site
 </pre>
 
-h2. 2. Run linkchecker
+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=$PWD/.site
+arvados/doc$ rake linkchecker baseurl=file://$PWD/.site
 </pre>
 
 Please note that this will regenerate your $PWD/.site directory.
 
-h2. 2. Preview HTML pages
+h2. Preview HTML pages
 
 <pre>
 arvados/doc$ rake run
@@ -46,7 +46,7 @@ arvados/doc$ rake run
 
 Preview the rendered pages at "http://localhost:8000":http://localhost:8000.
 
-h2. 3. Publish HTML pages inside Workbench
+h2. Publish HTML pages inside Workbench
 
 (or some other web site)
 
@@ -62,7 +62,7 @@ Make the docs appear at {workbench_host}/doc by creating a symbolic link in Work
 arvados/doc$ ln -sn ../../../doc/.site ../apps/workbench/public/doc
 </pre>
 
-h2. 4. Delete generated files
+h2. Delete generated files
 
 <pre>
 arvados/doc$ rake realclean

diff --git a/doc/Rakefile b/doc/Rakefile
index dbef7b97c5c6f1c285031305cb840fe8cb0f540f..6d7f4e115a22e9756cbe437fdec23864a81e2181 100644 (file)
--- a/doc/Rakefile
+++ b/doc/Rakefile
@@ -3,7 +3,7 @@
 require "rubygems"
 require "colorize"
 
-task :generate do
+task :generate => [ :realclean, 'sdk/python/arvados/index.html' ] do
   vars = ['baseurl', 'arvados_api_host', 'arvados_workbench_host']
   vars.each do |v|
     if ENV[v]
@@ -12,39 +12,34 @@ task :generate do
   end
 end
 
-task :linkchecker => [:realclean, :generate]
-
-task :linkchecker do
-  Dir.chdir(".site")
-  `which linkchecker`
+file "sdk/python/arvados/index.html" do |t|
+  `which epydoc`
   if $? == 0
-    ignore_urls = ['', 'javascript', 'mailto',
-                   'oftc.net', 'putty.org','google.com', 'fsf.org',
-                   'arvadosapi.com', 'arvados.org', 'sourceforge.net',
-                   'chiark.greenend.org.uk', 'github.io' ]
-    system "linkchecker index.html " + ignore_urls.join(' --ignore-url=')
+    `epydoc --html --parse-only -o sdk/python/arvados ../sdk/python/arvados/`
   else
-    puts "Warning: linkchecker not found, skipping".colorize(:light_red)
+    puts "Warning: epydoc not found, Python documentation will not be generated".colorize(:light_red)
   end
 end
 
-require "zenweb/tasks"
-load "zenweb-textile.rb"
-load "zenweb-liquid.rb"
-
-file "sdk/python/arvados/index.html" do |t|
-  `which epydoc`
-  if $? == 0
-    `epydoc --html -o sdk/python/arvados arvados`
-    Dir["sdk/python/arvados/*"].each do |f|
-      puts f
-      $website.pages[f] = Zenweb::Page.new($website, f)
+task :linkchecker => [ :generate ] do
+  Dir.chdir(".site") do
+    `which linkchecker`
+    if $? == 0
+      system "linkchecker index.html --ignore-url='!file://'"
+    else
+      puts "Warning: linkchecker not found, skipping run".colorize(:light_red)
     end
-  else
-    puts "Warning: epydoc not found, Python documentation will not be generated".colorize(:light_red)
   end
 end
 
+task :clean do
+  rm_rf "sdk/python/arvados"
+end
+
+require "zenweb/tasks"
+load "zenweb-textile.rb"
+load "zenweb-liquid.rb"
+
 task :extra_wirings do
   $website.pages["sdk/python/python.html.textile.liquid"].depends_on("sdk/python/arvados/index.html")
 end