Merge pull request #568 from edx/jkarni/fix/quietdocs
Jkarni/fix/quietdocs
This commit is contained in:
jkarni
@@ -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)
|
||||
|
||||
@@ -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/)
|
||||
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 = -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
|
||||
|
||||
|
||||
@@ -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 = -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
|
||||
|
||||
|
||||
@@ -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 = -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
|
||||
|
||||
|
||||
@@ -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)
|
||||
@@ -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.
|
||||
@@ -64,6 +65,46 @@ 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',
|
||||
]
|
||||
|
||||
if on_rtd:
|
||||
for mod_name in MOCK_MODULES:
|
||||
sys.modules[mod_name] = Mock()
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
|
||||
# from http://djangosnippets.org/snippets/2533/
|
||||
# autogenerate models definitions
|
||||
@@ -109,27 +150,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"""
|
||||
@@ -165,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
|
||||
|
||||
|
||||
|
||||
@@ -2,24 +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')
|
||||
end
|
||||
path = "docs"
|
||||
|
||||
Dir.chdir(path) do
|
||||
sh('make html')
|
||||
if args.quiet == 'verbose'
|
||||
sh('make html quiet=false')
|
||||
else
|
||||
sh('make html')
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
@@ -39,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 ---
|
||||
|
||||
@@ -40,12 +40,10 @@ 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')
|
||||
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
|
||||
end
|
||||
|
||||
Reference in New Issue
Block a user