Add verbose option

docs/Makefile

 
 .PHONY: html
 
+Q_FLAG =
+
+ifeq ($(quiet), true)
+Q_FLAG = quiet=true
+endif
+
 html:
-	@cd $(CURDIR)/data && make html
-	@cd $(CURDIR)/course_authors && make html
-	@cd $(CURDIR)/developers && make html
+	@cd $(CURDIR)/data && make html $(Q_FLAG)
+	@cd $(CURDIR)/course_authors && make html $(Q_FLAG)
+	@cd $(CURDIR)/developers && make html $(Q_FLAG)

docs/course_authors/Makefile

@@ -12,6 +12,12 @@ ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
 $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
 endif
 
+Q_FLAG        = 
+
+ifeq ($(quiet), true)
+Q_FLAG = -q
+endif
+
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter

docs/data/Makefile

@@ -7,6 +7,17 @@ SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = build
 
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+Q_FLAG        = 
+
+ifeq ($(quiet), true)
+Q_FLAG = -q
+endif
+
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter

docs/developers/Makefile

@@ -7,10 +7,21 @@ SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = build
 
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+Q_FLAG        = 
+
+ifeq ($(quiet), true)
+Q_FLAG = -q
+endif
+
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -q -d $(BUILDDIR)/doctrees -c source $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+ALLSPHINXOPTS   = $(Q_FLAG) -d $(BUILDDIR)/doctrees -c source $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 

rakelib/docs.rake

@@ -2,19 +2,24 @@ require 'launchy'
 
 # --- Develop and public documentation ---
 desc "Invoke sphinx 'make build' to generate docs."
-task :builddocs, [:options] do |t, args|
-    if args.options == 'dev'
+task :builddocs, [:type, :quiet] do |t, args|
+    args.with_defaults(:quiet => "quiet")
+    if args.type == 'dev'
         path = "docs/developer"
-    elsif args.options == 'author'
+    elsif args.type == 'author'
         path = "docs/course_authors"
-    elsif args.options == 'data'
+    elsif args.type == 'data'
         path = "docs/data"
     else
         path = "docs"
     end
 
     Dir.chdir(path) do
-        sh('make html')
+        if args.quiet == 'verbose'
+            sh('make html quiet=false')
+        else
+            sh('make html')
+        end
     end
 end
 
@@ -34,7 +39,7 @@ task :showdocs, [:options] do |t, args|
 end
 
 desc "Build docs and show them in browser"
-task :doc, [:options] =>  :builddocs do |t, args|
-    Rake::Task["showdocs"].invoke(args.options)
+task :doc, [:type, :quiet] =>  :builddocs do |t, args|
+    Rake::Task["showdocs"].invoke(args.type, args.quiet)
 end
 # --- Develop and public documentation ---

rakelib/tests.rake

@@ -40,9 +40,9 @@ end
 desc "Run documentation tests"
 task :test_docs do
     # Be sure that sphinx can build docs w/o exceptions.
-    test_message = "If test fails, you shoud run %s and look at whole output and fix exceptions.
+    test_message = "If test fails, you shoud run '%s' and look at whole output and fix exceptions.
 (You shouldn't fix rst warnings and errors for this to pass, just get rid of exceptions.)"
-    puts (test_message  % ["rake doc"]).colorize( :light_green )
+    puts (test_message  % ["rake doc[docs,verbose]"]).colorize( :light_green )
     test_sh('rake builddocs')
 end