From 332703c8568e668998e5dcfefc328bdcb3b19d47 Mon Sep 17 00:00:00 2001 From: Julian Arni Date: Fri, 2 Aug 2013 16:23:25 -0400 Subject: [PATCH 1/5] Fix repeated doc builds --- rakelib/docs.rake | 5 ----- rakelib/tests.rake | 4 +--- 2 files changed, 1 insertion(+), 8 deletions(-) diff --git a/rakelib/docs.rake b/rakelib/docs.rake index ce6c65f7fb..ddd2549f2b 100644 --- a/rakelib/docs.rake +++ b/rakelib/docs.rake @@ -13,11 +13,6 @@ task :builddocs, [:options] do |t, args| path = "docs" end - Dir.chdir(path) do - sh('make html') - end - path = "docs" - Dir.chdir(path) do sh('make html') end diff --git a/rakelib/tests.rake b/rakelib/tests.rake index 57861902bc..8b308efa15 100644 --- a/rakelib/tests.rake +++ b/rakelib/tests.rake @@ -44,8 +44,6 @@ task :test_docs do (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 ) test_sh('rake builddocs') - puts (test_message % ["rake doc[pub]"]).colorize( :light_green ) - test_sh('rake builddocs[pub]') end task :clean_test_files do @@ -161,4 +159,4 @@ task :coverage => :report_dirs do if not found_coverage_info puts "No coverage info found. Run `rake test` before running `rake coverage`." end -end \ No newline at end of file +end From 5c477a90045f49bc4d6cf120809dd62da5123d42 Mon Sep 17 00:00:00 2001 From: Julian Arni Date: Fri, 2 Aug 2013 16:24:07 -0400 Subject: [PATCH 2/5] Make builds quiet by default --- docs/course_authors/Makefile | 2 +- docs/data/Makefile | 2 +- docs/developers/Makefile | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/course_authors/Makefile b/docs/course_authors/Makefile index a9054b9932..0321201267 100644 --- a/docs/course_authors/Makefile +++ b/docs/course_authors/Makefile @@ -15,7 +15,7 @@ endif # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees -c source $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +ALLSPHINXOPTS = -q -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 diff --git a/docs/data/Makefile b/docs/data/Makefile index fd08639327..281415b978 100644 --- a/docs/data/Makefile +++ b/docs/data/Makefile @@ -10,7 +10,7 @@ BUILDDIR = build # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees -c source $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +ALLSPHINXOPTS = -q -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 diff --git a/docs/developers/Makefile b/docs/developers/Makefile index 168add14d6..868fc4a95b 100644 --- a/docs/developers/Makefile +++ b/docs/developers/Makefile @@ -10,7 +10,7 @@ BUILDDIR = build # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees -c source $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +ALLSPHINXOPTS = -q -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 From 0bbd80fedfea5f80f674c8c1dcefd18d80012df2 Mon Sep 17 00:00:00 2001 From: Julian Arni Date: Tue, 6 Aug 2013 14:00:31 -0400 Subject: [PATCH 3/5] Add verbose option --- docs/Makefile | 12 +++++++++--- docs/course_authors/Makefile | 6 ++++++ docs/data/Makefile | 11 +++++++++++ docs/developers/Makefile | 13 ++++++++++++- rakelib/docs.rake | 19 ++++++++++++------- rakelib/tests.rake | 4 ++-- 6 files changed, 52 insertions(+), 13 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 8e5e368266..3f441a2ef2 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,7 +1,13 @@ .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) diff --git a/docs/course_authors/Makefile b/docs/course_authors/Makefile index 0321201267..b05c2d944a 100644 --- a/docs/course_authors/Makefile +++ b/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 diff --git a/docs/data/Makefile b/docs/data/Makefile index 281415b978..272527a445 100644 --- a/docs/data/Makefile +++ b/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 diff --git a/docs/developers/Makefile b/docs/developers/Makefile index 868fc4a95b..65fea6d46e 100644 --- a/docs/developers/Makefile +++ b/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 diff --git a/rakelib/docs.rake b/rakelib/docs.rake index ddd2549f2b..3af50e2492 100644 --- a/rakelib/docs.rake +++ b/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 --- diff --git a/rakelib/tests.rake b/rakelib/tests.rake index 8b308efa15..f940c8f9c4 100644 --- a/rakelib/tests.rake +++ b/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 From 67167830093bad746fb45e32235cb7366dc916da Mon Sep 17 00:00:00 2001 From: Julian Arni Date: Tue, 6 Aug 2013 14:01:22 -0400 Subject: [PATCH 4/5] Fix import mocks. Prevents sphinx from bailing on builds that involve unavailable imports. --- docs/developers/source/conf.py | 63 ++++++++++++++++++++++------------ 1 file changed, 41 insertions(+), 22 deletions(-) diff --git a/docs/developers/source/conf.py b/docs/developers/source/conf.py index 12e9cf822b..8d33e07e9d 100644 --- a/docs/developers/source/conf.py +++ b/docs/developers/source/conf.py @@ -3,7 +3,7 @@ #pylint: disable=W0622 #pylint: disable=W0212 #pylint: disable=W0613 - + import sys, os on_rtd = os.environ.get('READTHEDOCS', None) == 'True' @@ -26,7 +26,7 @@ html_static_path.append('source/_static') # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('../../..')) +sys.path.insert(0, os.path.abspath('../../..')) root = os.path.abspath('../../..') sys.path.append(root) @@ -64,6 +64,45 @@ exclude_patterns = ['build'] # Output file base name for HTML help builder. htmlhelp_basename = 'edXDocs' +# --- Mock modules ------------------------------------------------------------ + +# Mock all the modules that the readthedocs build can't import +import mock + +class Mock(object): + def __init__(self, *args, **kwargs): + pass + + def __call__(self, *args, **kwargs): + return Mock() + + @classmethod + def __getattr__(cls, name): + if name in ('__file__', '__path__'): + return '/dev/null' + elif name[0] == name[0].upper(): + mockType = type(name, (), {}) + mockType.__module__ = __name__ + return mockType + else: + return Mock() + +# The list of modules and submodules that we know give RTD trouble. +# Make sure you've tried including the relevant package in +# docs/share/requirements.txt before adding to this list. +MOCK_MODULES = [ + 'numpy', + 'matplotlib', + 'matplotlib.pyplot', + 'scipy.interpolate', + 'scipy.constants', + 'scipy.optimize', + ] + +for mod_name in MOCK_MODULES: + sys.modules[mod_name] = Mock() + +# ----------------------------------------------------------------------------- # from http://djangosnippets.org/snippets/2533/ # autogenerate models definitions @@ -109,27 +148,7 @@ def strip_tags(html): s.feed(html) return s.get_data() -class Mock(object): - def __init__(self, *args, **kwargs): - pass - def __call__(self, *args, **kwargs): - return Mock() - - @classmethod - def __getattr__(cls, name): - if name in ('__file__', '__path__'): - return '/dev/null' - elif name[0] == name[0].upper(): - mockType = type(name, (), {}) - mockType.__module__ = __name__ - return mockType - else: - return Mock() - -MOCK_MODULES = ['scipy', 'numpy'] -for mod_name in MOCK_MODULES: - sys.modules[mod_name] = Mock() def process_docstring(app, what, name, obj, options, lines): """Autodoc django models""" From 852977c2d2e3e641b0af36bcfb29b3c0497cd8ab Mon Sep 17 00:00:00 2001 From: Julian Arni Date: Mon, 19 Aug 2013 10:24:52 -0400 Subject: [PATCH 5/5] Mock only if on RTD. And some code cleanup. --- docs/developers/source/conf.py | 38 ++++++---------------------------- 1 file changed, 6 insertions(+), 32 deletions(-) diff --git a/docs/developers/source/conf.py b/docs/developers/source/conf.py index 8d33e07e9d..3036519fce 100644 --- a/docs/developers/source/conf.py +++ b/docs/developers/source/conf.py @@ -53,8 +53,9 @@ else: # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [ - 'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', - 'sphinx.ext.pngmath', 'sphinx.ext.mathjax', 'sphinx.ext.viewcode'] + 'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', + 'sphinx.ext.mathjax', 'sphinx.ext.viewcode'] # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. @@ -99,8 +100,9 @@ MOCK_MODULES = [ 'scipy.optimize', ] -for mod_name in MOCK_MODULES: - sys.modules[mod_name] = Mock() +if on_rtd: + for mod_name in MOCK_MODULES: + sys.modules[mod_name] = Mock() # ----------------------------------------------------------------------------- @@ -184,34 +186,6 @@ def process_docstring(app, what, name, obj, options, lines): # Add the field's type to the docstring lines.append(u':type %s: %s' % (field.attname, type(field).__name__)) - # Only look at objects that inherit from Django's base FORM class - # elif (inspect.isclass(obj) and issubclass(obj, forms.ModelForm) or issubclass(obj, forms.ModelForm) or issubclass(obj, BaseInlineFormSet)): - # pass - # # Grab the field list from the meta class - # import ipdb; ipdb.set_trace() - # fields = obj._meta._fields() - # import ipdb; ipdb.set_trace() - # for field in fields: - # import ipdb; ipdb.set_trace() - # # Decode and strip any html out of the field's help text - # help_text = strip_tags(force_unicode(field.help_text)) - - # # Decode and capitalize the verbose name, for use if there isn't - # # any help text - # verbose_name = force_unicode(field.verbose_name).capitalize() - - # if help_text: - # # Add the model field to the end of the docstring as a param - # # using the help text as the description - # lines.append(u':param %s: %s' % (field.attname, help_text)) - # else: - # # Add the model field to the end of the docstring as a param - # # using the verbose name as the description - # lines.append(u':param %s: %s' % (field.attname, verbose_name)) - - # # Add the field's type to the docstring - # lines.append(u':type %s: %s' % (field.attname, type(field).__name__)) - # Return the extended docstring return lines