Skip to content

E
edx-platform
Commit 424570c6 by jkarni
Options

Merge pull request #568 from edx/jkarni/fix/quietdocs 

Jkarni/fix/quietdocs
parents bd45103f 852977c2
Showing with 100 additions and 76 deletions
docs/Makefile
.PHONY: html .PHONY: html
Q_FLAG =
ifeq ($(quiet), true)
Q_FLAG = quiet=true
endif
html: html:
@cd $(CURDIR)/data && make html @cd $(CURDIR)/data && make html $(Q_FLAG)
@cd $(CURDIR)/course_authors && make html @cd $(CURDIR)/course_authors && make html $(Q_FLAG)
@cd $(CURDIR)/developers && make html @cd $(CURDIR)/developers && make html $(Q_FLAG)
docs/course_authors/Makefile
...@@ -12,10 +12,16 @@ ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) ...@@ -12,10 +12,16 @@ 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/) $(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 endif
Q_FLAG =
ifeq ($(quiet), true)
Q_FLAG = -q
endif
# Internal variables. # Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter 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 # the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
......
docs/data/Makefile
...@@ -7,10 +7,21 @@ SPHINXBUILD = sphinx-build ...@@ -7,10 +7,21 @@ SPHINXBUILD = sphinx-build
PAPER = PAPER =
BUILDDIR = build 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. # Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter 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 # the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
......
docs/developers/Makefile
...@@ -7,10 +7,21 @@ SPHINXBUILD = sphinx-build ...@@ -7,10 +7,21 @@ SPHINXBUILD = sphinx-build
PAPER = PAPER =
BUILDDIR = build 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. # Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -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 # the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
......
docs/developers/source/conf.py
...@@ -3,7 +3,7 @@ ...@@ -3,7 +3,7 @@
#pylint: disable=W0622 #pylint: disable=W0622
#pylint: disable=W0212 #pylint: disable=W0212
#pylint: disable=W0613 #pylint: disable=W0613
import sys, os import sys, os
on_rtd = os.environ.get('READTHEDOCS', None) == 'True' on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
...@@ -26,7 +26,7 @@ html_static_path.append('source/_static') ...@@ -26,7 +26,7 @@ html_static_path.append('source/_static')
# If extensions (or modules to document with autodoc) are in another directory, # 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 # 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. # 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('../../..') root = os.path.abspath('../../..')
sys.path.append(root) sys.path.append(root)
...@@ -53,8 +53,9 @@ else: ...@@ -53,8 +53,9 @@ else:
# Add any Sphinx extension module names here, as strings. They can be extensions # Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [ extensions = [
'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx',
'sphinx.ext.pngmath', 'sphinx.ext.mathjax', 'sphinx.ext.viewcode'] '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 # List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files. # directories to ignore when looking for source files.
...@@ -64,6 +65,46 @@ exclude_patterns = ['build'] ...@@ -64,6 +65,46 @@ exclude_patterns = ['build']
# Output file base name for HTML help builder. # Output file base name for HTML help builder.
htmlhelp_basename = 'edXDocs' 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',
]
if on_rtd:
for mod_name in MOCK_MODULES:
sys.modules[mod_name] = Mock()
# -----------------------------------------------------------------------------
# from http://djangosnippets.org/snippets/2533/ # from http://djangosnippets.org/snippets/2533/
# autogenerate models definitions # autogenerate models definitions
...@@ -109,27 +150,7 @@ def strip_tags(html): ...@@ -109,27 +150,7 @@ def strip_tags(html):
s.feed(html) s.feed(html)
return s.get_data() 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): def process_docstring(app, what, name, obj, options, lines):
"""Autodoc django models""" """Autodoc django models"""
...@@ -165,34 +186,6 @@ def process_docstring(app, what, name, obj, options, lines): ...@@ -165,34 +186,6 @@ def process_docstring(app, what, name, obj, options, lines):
# Add the field's type to the docstring # Add the field's type to the docstring
lines.append(u':type %s: %s' % (field.attname, type(field).__name__)) 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 return lines
......
rakelib/docs.rake
...@@ -2,24 +2,24 @@ require 'launchy' ...@@ -2,24 +2,24 @@ require 'launchy'
# --- Develop and public documentation --- # --- Develop and public documentation ---
desc "Invoke sphinx 'make build' to generate docs." desc "Invoke sphinx 'make build' to generate docs."
task :builddocs, [:options] do |t, args| task :builddocs, [:type, :quiet] do |t, args|
if args.options == 'dev' args.with_defaults(:quiet => "quiet")
if args.type == 'dev'
path = "docs/developer" path = "docs/developer"
elsif args.options == 'author' elsif args.type == 'author'
path = "docs/course_authors" path = "docs/course_authors"
elsif args.options == 'data' elsif args.type == 'data'
path = "docs/data" path = "docs/data"
else else
path = "docs" path = "docs"
end end
Dir.chdir(path) do Dir.chdir(path) do
sh('make html') if args.quiet == 'verbose'
end sh('make html quiet=false')
path = "docs" else
sh('make html')
Dir.chdir(path) do end
sh('make html')
end end
end end
...@@ -39,7 +39,7 @@ task :showdocs, [:options] do |t, args| ...@@ -39,7 +39,7 @@ task :showdocs, [:options] do |t, args|
end end
desc "Build docs and show them in browser" desc "Build docs and show them in browser"
task :doc, [:options] => :builddocs do |t, args| task :doc, [:type, :quiet] => :builddocs do |t, args|
Rake::Task["showdocs"].invoke(args.options) Rake::Task["showdocs"].invoke(args.type, args.quiet)
end end
# --- Develop and public documentation --- # --- Develop and public documentation ---
rakelib/tests.rake
...@@ -40,12 +40,10 @@ end ...@@ -40,12 +40,10 @@ end
desc "Run documentation tests" desc "Run documentation tests"
task :test_docs do task :test_docs do
# Be sure that sphinx can build docs w/o exceptions. # 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.)" (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') test_sh('rake builddocs')
puts (test_message % ["rake doc[pub]"]).colorize( :light_green )
test_sh('rake builddocs[pub]')
end end
task :clean_test_files do task :clean_test_files do
...@@ -161,4 +159,4 @@ task :coverage => :report_dirs do ...@@ -161,4 +159,4 @@ task :coverage => :report_dirs do
if not found_coverage_info if not found_coverage_info
puts "No coverage info found. Run `rake test` before running `rake coverage`." puts "No coverage info found. Run `rake test` before running `rake coverage`."
end end
end end
\ No newline at end of file
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment