From 0dceb5d678470be9975dc7f90f2fa8b0abded9d4 Mon Sep 17 00:00:00 2001 From: Caroline De Brouwer Date: Mon, 6 Jul 2015 17:04:33 +0200 Subject: [PATCH 01/26] Begin script for generic easyblock documentation --- easybuild/tools/docs.py | 63 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 59 insertions(+), 4 deletions(-) diff --git a/easybuild/tools/docs.py b/easybuild/tools/docs.py index 628d6d5b2f..795656db59 100644 --- a/easybuild/tools/docs.py +++ b/easybuild/tools/docs.py @@ -34,25 +34,27 @@ @author: Ward Poelmans (Ghent University) """ import copy +import os from easybuild.framework.easyconfig.default import DEFAULT_CONFIG, HIDDEN, sorted_categories from easybuild.framework.easyconfig.easyconfig import get_easyblock_class from easybuild.tools.ordereddict import OrderedDict from easybuild.tools.utilities import quote_str +from easybuild.easyblocks.generic.configuremake import ConfigureMake FORMAT_RST = 'rst' FORMAT_TXT = 'txt' +def det_col_width(entries, title): + """Determine column width based on column title and list of entries.""" + return max(map(len, entries + [title])) + def avail_easyconfig_params_rst(title, grouped_params): """ Compose overview of available easyconfig parameters, in RST format. """ - def det_col_width(entries, title): - """Determine column width based on column title and list of entries.""" - return max(map(len, entries + [title])) - # main title lines = [ title, @@ -160,3 +162,56 @@ def avail_easyconfig_params(easyblock, output_format): FORMAT_TXT: avail_easyconfig_params_txt, } return avail_easyconfig_params_functions[output_format](title, grouped_params) + +def generic_easyblocks(classname): + """ + Compose overview of available generic easyblocks in rst format + """ + block = globals()[classname] + lines = [ + '``' + classname + '``', + '=' * (len(classname)+4), + '', + ] + + derived = '(derives from ' + for base in block.__bases__: + derived += '``'+base.__name__+'`` ' + derived += ')' + lines.extend([derived, '']) + + lines.extend([block.__doc__.strip(), '']) + + if block.extra_options(None): + extra_parameters = 'Extra easyconfig parameters specific to ``' + classname + '`` easyblock' + lines.extend([extra_parameters, '-' * len(extra_parameters), '']) + ex_opt = block.extra_options() + + ectitle = 'easyconfig parameter' + desctitle = 'description' + dftitle = 'default value' + + # figure out column widths + nw = det_col_width([key for key in ex_opt], ectitle) + 4 # +4 for backticks + dw = det_col_width([val[1] for val in ex_opt.values()], desctitle) + dfw = det_col_width([str(val[0]) for val in ex_opt.values()], dftitle) + 4 # +4 for backticks + + # table aligning - I may have stolen this from above but hey ho I'll fix that later + line_tmpl = "{0:{c}<%s} {1:{c}<%s} {2:{c}<%s}" % (nw, dw, dfw) + table_line = line_tmpl.format('', '', '', c='=', nw=nw, dw=dw, dfw=dfw) + + lines.append(table_line) + lines.append(line_tmpl.format(ectitle, desctitle, dftitle, c=' ')) + lines.append(table_line) + + for key in ex_opt: + lines.append(line_tmpl.format('``'+key+'``', ex_opt[key][1], '``' + str(quote_str(ex_opt[key][0])) + '``', c=' ')) + lines.append(table_line) + + commonly_used = 'Commonly used easyconfig parameters with ``' + classname + '`` easyblock' + lines.extend(['', commonly_used, '-' * len(commonly_used)]) + + print '\n'.join(lines) + + + From 8fbc168a485b308020a035a9cc1bf1fc7688a2b9 Mon Sep 17 00:00:00 2001 From: Caroline De Brouwer Date: Tue, 7 Jul 2015 13:57:40 +0200 Subject: [PATCH 02/26] Generic easyblock docs, continued --- easybuild/tools/doc_examples/Binary.eb | 21 ++++++ easybuild/tools/doc_examples/Bundle.eb | 17 +++++ easybuild/tools/doc_examples/CMakeMake.eb | 30 ++++++++ easybuild/tools/doc_examples/ConfigureMake.eb | 20 +++++ .../ConfigureMakePythonPackage.eb | 33 ++++++++ easybuild/tools/docs.py | 75 ++++++++++++++----- 6 files changed, 179 insertions(+), 17 deletions(-) create mode 100644 easybuild/tools/doc_examples/Binary.eb create mode 100644 easybuild/tools/doc_examples/Bundle.eb create mode 100644 easybuild/tools/doc_examples/CMakeMake.eb create mode 100644 easybuild/tools/doc_examples/ConfigureMake.eb create mode 100644 easybuild/tools/doc_examples/ConfigureMakePythonPackage.eb diff --git a/easybuild/tools/doc_examples/Binary.eb b/easybuild/tools/doc_examples/Binary.eb new file mode 100644 index 0000000000..2fa31617c3 --- /dev/null +++ b/easybuild/tools/doc_examples/Binary.eb @@ -0,0 +1,21 @@ +easyblock = 'Binary' + +name = 'Platanus' +version = '1.2.1' +versionsuffix = '-linux-x86_64' + +homepage = 'http://platanus.bio.titech.ac.jp/' +description = """PLATform for Assembling NUcleotide Sequences""" + +toolchain = {'name': 'dummy', 'version': 'dummy'} + +source_urls = ['http://platanus.bio.titech.ac.jp/Platanus_release/20130901010201'] +sources = ['platanus'] +checksums = ['02cf92847ec704d010a54df293b9c60a'] + +sanity_check_paths = { + 'files': ['platanus'], + 'dirs': [], +} + +moduleclass = 'bio' diff --git a/easybuild/tools/doc_examples/Bundle.eb b/easybuild/tools/doc_examples/Bundle.eb new file mode 100644 index 0000000000..067ccdbe63 --- /dev/null +++ b/easybuild/tools/doc_examples/Bundle.eb @@ -0,0 +1,17 @@ +easyblock = 'Bundle' + +name = 'Autotools' +version = '20150119' # date of the most recent change + +homepage = 'http://autotools.io' +description = """This bundle collect the standard GNU build tools: Autoconf, Automake and libtool""" + +toolchain = {'name': 'GCC', 'version': '4.9.2'} + +dependencies = [ + ('Autoconf', '2.69'), # 20120424 + ('Automake', '1.15'), # 20150105 + ('libtool', '2.4.5'), # 20150119 +] + +moduleclass = 'devel' diff --git a/easybuild/tools/doc_examples/CMakeMake.eb b/easybuild/tools/doc_examples/CMakeMake.eb new file mode 100644 index 0000000000..1e8a2bf6f6 --- /dev/null +++ b/easybuild/tools/doc_examples/CMakeMake.eb @@ -0,0 +1,30 @@ +easyblock = 'CMakeMake' + +name = 'ANTs' +version = '2.1.0rc3' + +homepage = 'http://stnava.github.io/ANTs/' +description = """ANTs extracts information from complex datasets that include imaging. ANTs is useful for managing, + interpreting and visualizing multidimensional data.""" + +toolchain = {'name': 'goolf', 'version': '1.5.14'} +toolchainopts = {'pic': True} + +source_urls = ['https://github.com/stnava/ANTs/archive/'] +sources = ['v%(version)s.tar.gz'] + +builddependencies = [('CMake', '3.0.2')] + +skipsteps = ['install'] +buildopts = ' && mkdir -p %(installdir)s && cp -r * %(installdir)s/' + +parallel = 1 + +separate_build_dir = True + +sanity_check_paths = { + 'files': ['bin/ANTS'], + 'dirs': ['lib'], +} + +moduleclass = 'data' diff --git a/easybuild/tools/doc_examples/ConfigureMake.eb b/easybuild/tools/doc_examples/ConfigureMake.eb new file mode 100644 index 0000000000..9a0d4bf65e --- /dev/null +++ b/easybuild/tools/doc_examples/ConfigureMake.eb @@ -0,0 +1,20 @@ +easyblock = 'ConfigureMake' + +name = 'zsync' +version = '0.6.2' + +homepage = 'http://zsync.moria.org.uk/' +description = """zsync-0.6.2: Optimising file distribution program, a 1-to-many rsync""" + +sources = [SOURCE_TAR_BZ2] +source_urls = ['http://zsync.moria.org.uk/download/'] + + +toolchain = {'name': 'ictce', 'version': '5.3.0'} + +sanity_check_paths = { + 'files': ['bin/zsync'], + 'dirs': [] + } + +moduleclass = 'tools' diff --git a/easybuild/tools/doc_examples/ConfigureMakePythonPackage.eb b/easybuild/tools/doc_examples/ConfigureMakePythonPackage.eb new file mode 100644 index 0000000000..0f9fd09a84 --- /dev/null +++ b/easybuild/tools/doc_examples/ConfigureMakePythonPackage.eb @@ -0,0 +1,33 @@ +easyblock = 'ConfigureMakePythonPackage' + +name = 'PyQt' +version = '4.11.3' + +homepage = 'http://www.riverbankcomputing.co.uk/software/pyqt' +description = """PyQt is a set of Python v2 and v3 bindings for Digia's Qt application framework.""" + +toolchain = {'name': 'goolf', 'version': '1.5.14'} + +sources = ['%(name)s-x11-gpl-%(version)s.tar.gz'] +source_urls = ['http://sourceforge.net/projects/pyqt/files/PyQt4/PyQt-%(version)s'] + +python = 'Python' +pyver = '2.7.9' +pythonshortver = '.'.join(pyver.split('.')[:2]) +versionsuffix = '-%s-%s' % (python, pyver) + +dependencies = [ + (python, pyver), + ('SIP', '4.16.4', versionsuffix), + ('Qt', '4.8.6'), +] + +configopts = "configure-ng.py --confirm-license" +configopts += " --destdir=%%(installdir)s/lib/python%s/site-packages " % pythonshortver +configopts += " --no-sip-files" + +options = {'modulename': 'PyQt4'} + +modextrapaths = {'PYTHONPATH': 'lib/python%s/site-packages' % pythonshortver} + +moduleclass = 'vis' diff --git a/easybuild/tools/docs.py b/easybuild/tools/docs.py index 795656db59..709405dc74 100644 --- a/easybuild/tools/docs.py +++ b/easybuild/tools/docs.py @@ -34,14 +34,14 @@ @author: Ward Poelmans (Ghent University) """ import copy +import inspect import os from easybuild.framework.easyconfig.default import DEFAULT_CONFIG, HIDDEN, sorted_categories from easybuild.framework.easyconfig.easyconfig import get_easyblock_class from easybuild.tools.ordereddict import OrderedDict -from easybuild.tools.utilities import quote_str -from easybuild.easyblocks.generic.configuremake import ConfigureMake - +from easybuild.tools.utilities import quote_str, import_available_modules +from easybuild.tools.filetools import read_file FORMAT_RST = 'rst' FORMAT_TXT = 'txt' @@ -163,29 +163,56 @@ def avail_easyconfig_params(easyblock, output_format): } return avail_easyconfig_params_functions[output_format](title, grouped_params) -def generic_easyblocks(classname): +def generic_easyblocks(): """ - Compose overview of available generic easyblocks in rst format + Compose overview of all generic easyblocks """ - block = globals()[classname] + modules = import_available_modules('easybuild.easyblocks.generic') + docs = [] + seen = [] + + for m in modules: + for name,obj in inspect.getmembers(m, inspect.isclass): + eb_class = getattr(m, name) + # skip imported classes that are not easyblocks + if eb_class.__module__.startswith('easybuild.easyblocks.generic') and name not in seen: + docs.append(doc_easyblock(eb_class)) + seen.append(name) + + return docs + + +def doc_easyblock(eb_class): + """ + Compose overview of one easyblock given class object of the easyblock in rst format + """ + classname = eb_class.__name__ + + common_params = { + 'ConfigureMake' : ['configopts', 'buildopts', 'installopts'], + # to be continued + } + lines = [ '``' + classname + '``', '=' * (len(classname)+4), '', ] - derived = '(derives from ' - for base in block.__bases__: - derived += '``'+base.__name__+'`` ' - derived += ')' + bases = ['``' + base.__name__ + '``' for base in eb_class.__bases__] + derived = '(derives from ' + ', '.join(bases) + ')' + + lines.extend([derived, '']) - lines.extend([block.__doc__.strip(), '']) + # Description (docstring) + lines.extend([eb_class.__doc__.strip(), '']) - if block.extra_options(None): + # Add extra options, if any + if eb_class.extra_options(): extra_parameters = 'Extra easyconfig parameters specific to ``' + classname + '`` easyblock' lines.extend([extra_parameters, '-' * len(extra_parameters), '']) - ex_opt = block.extra_options() + ex_opt = eb_class.extra_options() ectitle = 'easyconfig parameter' desctitle = 'description' @@ -196,7 +223,7 @@ def generic_easyblocks(classname): dw = det_col_width([val[1] for val in ex_opt.values()], desctitle) dfw = det_col_width([str(val[0]) for val in ex_opt.values()], dftitle) + 4 # +4 for backticks - # table aligning - I may have stolen this from above but hey ho I'll fix that later + # table aligning line_tmpl = "{0:{c}<%s} {1:{c}<%s} {2:{c}<%s}" % (nw, dw, dfw) table_line = line_tmpl.format('', '', '', c='=', nw=nw, dw=dw, dfw=dfw) @@ -206,12 +233,26 @@ def generic_easyblocks(classname): for key in ex_opt: lines.append(line_tmpl.format('``'+key+'``', ex_opt[key][1], '``' + str(quote_str(ex_opt[key][0])) + '``', c=' ')) - lines.append(table_line) + lines.extend([table_line, '']) + + if classname in common_params: commonly_used = 'Commonly used easyconfig parameters with ``' + classname + '`` easyblock' - lines.extend(['', commonly_used, '-' * len(commonly_used)]) + lines.extend([commonly_used, '-' * len(commonly_used)]) - print '\n'.join(lines) + for opt in common_params[classname]: + param = '* ``' + opt + '`` - ' + DEFAULT_CONFIG[opt][1] + lines.append(param) + + + if classname + '.eb' in os.listdir(os.path.join(os.path.dirname(__file__), 'doc_examples')): + lines.extend(['', 'Example', '-' * 8, '', '::', '']) + f = open(os.path.join(os.path.dirname(__file__), 'doc_examples', classname+'.eb'), "r") + for line in f.readlines(): + lines.append(' ' + line.strip()) + lines.append('') # empty line after literal block + + return '\n'.join(lines) From 7cfc6a295425bc06eacde370e1035c24f6ff66c0 Mon Sep 17 00:00:00 2001 From: Caroline De Brouwer Date: Tue, 7 Jul 2015 15:54:47 +0200 Subject: [PATCH 03/26] python star operator is gr8 --- easybuild/tools/docs.py | 69 +++++++++++++++++++++++++++++------------ 1 file changed, 49 insertions(+), 20 deletions(-) diff --git a/easybuild/tools/docs.py b/easybuild/tools/docs.py index 709405dc74..1e2e701e44 100644 --- a/easybuild/tools/docs.py +++ b/easybuild/tools/docs.py @@ -179,7 +179,7 @@ def generic_easyblocks(): docs.append(doc_easyblock(eb_class)) seen.append(name) - return docs + return sorted(docs) def doc_easyblock(eb_class): @@ -214,26 +214,10 @@ def doc_easyblock(eb_class): lines.extend([extra_parameters, '-' * len(extra_parameters), '']) ex_opt = eb_class.extra_options() - ectitle = 'easyconfig parameter' - desctitle = 'description' - dftitle = 'default value' + titles = ['easyconfig parameter', 'description', 'default value'] + values = [[backtick(key) for key in ex_opt], [val[1] for val in ex_opt.values()], [backtick(str(quote_str(val[0]))) for val in ex_opt.values()]] - # figure out column widths - nw = det_col_width([key for key in ex_opt], ectitle) + 4 # +4 for backticks - dw = det_col_width([val[1] for val in ex_opt.values()], desctitle) - dfw = det_col_width([str(val[0]) for val in ex_opt.values()], dftitle) + 4 # +4 for backticks - - # table aligning - line_tmpl = "{0:{c}<%s} {1:{c}<%s} {2:{c}<%s}" % (nw, dw, dfw) - table_line = line_tmpl.format('', '', '', c='=', nw=nw, dw=dw, dfw=dfw) - - lines.append(table_line) - lines.append(line_tmpl.format(ectitle, desctitle, dftitle, c=' ')) - lines.append(table_line) - - for key in ex_opt: - lines.append(line_tmpl.format('``'+key+'``', ex_opt[key][1], '``' + str(quote_str(ex_opt[key][0])) + '``', c=' ')) - lines.extend([table_line, '']) + lines.extend(mk_rst_table(titles, values)) if classname in common_params: @@ -255,4 +239,49 @@ def doc_easyblock(eb_class): return '\n'.join(lines) +def mk_rst_table(titles, values): + """ + Returns an rst table with given titles and string values + """ + num_col = len(titles) + table = [] + col_widths = [] + tmpl = [] + line= [] + + # figure out column widths + for i in range(0, num_col): + col_widths.append(det_col_width(values[i], titles[i])) + + # make line template + tmpl.append('{' + str(i) + ':{c}<' + str(col_widths[i]) + '}') + line.append('') # needed for table line + + line_tmpl = ' '.join(tmpl) + table_line = line_tmpl.format(*line, c="=") + + table.append(table_line) + table.append(line_tmpl.format(*titles, c=' ')) + table.append(table_line) + + for i in range(0, len(values[0])): + table.append(line_tmpl.format(*[v[i] for v in values], c=' ')) + + table.extend([table_line, '']) + + return table + + +def backtick(string): + return '``' + string + '``' + + + + + + + + + + From 31587c911254009a42282eb05d12bc86b244b603 Mon Sep 17 00:00:00 2001 From: Caroline De Brouwer Date: Tue, 7 Jul 2015 15:54:47 +0200 Subject: [PATCH 04/26] Separate function for making rst tables --- easybuild/tools/docs.py | 69 +++++++++++++++++++++++++++++------------ 1 file changed, 49 insertions(+), 20 deletions(-) diff --git a/easybuild/tools/docs.py b/easybuild/tools/docs.py index 709405dc74..1e2e701e44 100644 --- a/easybuild/tools/docs.py +++ b/easybuild/tools/docs.py @@ -179,7 +179,7 @@ def generic_easyblocks(): docs.append(doc_easyblock(eb_class)) seen.append(name) - return docs + return sorted(docs) def doc_easyblock(eb_class): @@ -214,26 +214,10 @@ def doc_easyblock(eb_class): lines.extend([extra_parameters, '-' * len(extra_parameters), '']) ex_opt = eb_class.extra_options() - ectitle = 'easyconfig parameter' - desctitle = 'description' - dftitle = 'default value' + titles = ['easyconfig parameter', 'description', 'default value'] + values = [[backtick(key) for key in ex_opt], [val[1] for val in ex_opt.values()], [backtick(str(quote_str(val[0]))) for val in ex_opt.values()]] - # figure out column widths - nw = det_col_width([key for key in ex_opt], ectitle) + 4 # +4 for backticks - dw = det_col_width([val[1] for val in ex_opt.values()], desctitle) - dfw = det_col_width([str(val[0]) for val in ex_opt.values()], dftitle) + 4 # +4 for backticks - - # table aligning - line_tmpl = "{0:{c}<%s} {1:{c}<%s} {2:{c}<%s}" % (nw, dw, dfw) - table_line = line_tmpl.format('', '', '', c='=', nw=nw, dw=dw, dfw=dfw) - - lines.append(table_line) - lines.append(line_tmpl.format(ectitle, desctitle, dftitle, c=' ')) - lines.append(table_line) - - for key in ex_opt: - lines.append(line_tmpl.format('``'+key+'``', ex_opt[key][1], '``' + str(quote_str(ex_opt[key][0])) + '``', c=' ')) - lines.extend([table_line, '']) + lines.extend(mk_rst_table(titles, values)) if classname in common_params: @@ -255,4 +239,49 @@ def doc_easyblock(eb_class): return '\n'.join(lines) +def mk_rst_table(titles, values): + """ + Returns an rst table with given titles and string values + """ + num_col = len(titles) + table = [] + col_widths = [] + tmpl = [] + line= [] + + # figure out column widths + for i in range(0, num_col): + col_widths.append(det_col_width(values[i], titles[i])) + + # make line template + tmpl.append('{' + str(i) + ':{c}<' + str(col_widths[i]) + '}') + line.append('') # needed for table line + + line_tmpl = ' '.join(tmpl) + table_line = line_tmpl.format(*line, c="=") + + table.append(table_line) + table.append(line_tmpl.format(*titles, c=' ')) + table.append(table_line) + + for i in range(0, len(values[0])): + table.append(line_tmpl.format(*[v[i] for v in values], c=' ')) + + table.extend([table_line, '']) + + return table + + +def backtick(string): + return '``' + string + '``' + + + + + + + + + + From 34c2853b4a848e36c1cba294816fc713c6a656dd Mon Sep 17 00:00:00 2001 From: Caroline De Brouwer Date: Tue, 7 Jul 2015 16:29:40 +0200 Subject: [PATCH 05/26] Also use mk_rst_table in avail_easyconfig_params --- easybuild/tools/docs.py | 41 ++++++++++++----------------------------- 1 file changed, 12 insertions(+), 29 deletions(-) diff --git a/easybuild/tools/docs.py b/easybuild/tools/docs.py index 1e2e701e44..aa6cc45387 100644 --- a/easybuild/tools/docs.py +++ b/easybuild/tools/docs.py @@ -67,29 +67,14 @@ def avail_easyconfig_params_rst(title, grouped_params): lines.append("%s parameters" % grpname) lines.extend(['-' * len(lines[-1]), '']) - name_title = "**Parameter name**" - descr_title = "**Description**" - dflt_title = "**Default value**" + titles = ["**Parameter name**", "**Description**", "**Default value**"] + values = [ + [backtick(name) for name in grouped_params[grpname].keys()], + [x[0] for x in grouped_params[grpname].values()], + [str(quote_str(x[1])) for x in grouped_params[grpname].values()] + ] - # figure out column widths - nw = det_col_width(grouped_params[grpname].keys(), name_title) + 4 # +4 for raw format ("``foo``") - dw = det_col_width([x[0] for x in grouped_params[grpname].values()], descr_title) - dfw = det_col_width([str(quote_str(x[1])) for x in grouped_params[grpname].values()], dflt_title) - - # 3 columns (name, description, default value), left-aligned, {c} is fill char - line_tmpl = "{0:{c}<%s} {1:{c}<%s} {2:{c}<%s}" % (nw, dw, dfw) - table_line = line_tmpl.format('', '', '', c='=', nw=nw, dw=dw, dfw=dfw) - - # table header - lines.append(table_line) - lines.append(line_tmpl.format(name_title, descr_title, dflt_title, c=' ')) - lines.append(line_tmpl.format('', '', '', c='-')) - - # table rows by parameter - for name, (descr, dflt) in sorted(grouped_params[grpname].items()): - rawname = '``%s``' % name - lines.append(line_tmpl.format(rawname, descr, str(quote_str(dflt)), c=' ')) - lines.append(table_line) + lines.extend(mk_rst_table(titles, values)) lines.append('') return '\n'.join(lines) @@ -201,8 +186,6 @@ def doc_easyblock(eb_class): bases = ['``' + base.__name__ + '``' for base in eb_class.__bases__] derived = '(derives from ' + ', '.join(bases) + ')' - - lines.extend([derived, '']) # Description (docstring) @@ -210,7 +193,7 @@ def doc_easyblock(eb_class): # Add extra options, if any if eb_class.extra_options(): - extra_parameters = 'Extra easyconfig parameters specific to ``' + classname + '`` easyblock' + extra_parameters = 'Extra easyconfig parameters specific to ' + backtick(classname) + ' easyblock' lines.extend([extra_parameters, '-' * len(extra_parameters), '']) ex_opt = eb_class.extra_options() @@ -218,14 +201,14 @@ def doc_easyblock(eb_class): values = [[backtick(key) for key in ex_opt], [val[1] for val in ex_opt.values()], [backtick(str(quote_str(val[0]))) for val in ex_opt.values()]] lines.extend(mk_rst_table(titles, values)) - + lines.append('') if classname in common_params: - commonly_used = 'Commonly used easyconfig parameters with ``' + classname + '`` easyblock' + commonly_used = 'Commonly used easyconfig parameters with ' + backtick(classname) + ' easyblock' lines.extend([commonly_used, '-' * len(commonly_used)]) for opt in common_params[classname]: - param = '* ``' + opt + '`` - ' + DEFAULT_CONFIG[opt][1] + param = '* ' + backtick(opt) + ' - ' + DEFAULT_CONFIG[opt][1] lines.append(param) @@ -241,7 +224,7 @@ def doc_easyblock(eb_class): def mk_rst_table(titles, values): """ - Returns an rst table with given titles and string values + Returns an rst table with given titles and values (a nested list of string values for each column) """ num_col = len(titles) table = [] From e96df9a754167fcb3bca99493456d2722ceb8a19 Mon Sep 17 00:00:00 2001 From: Caroline De Brouwer Date: Tue, 7 Jul 2015 16:50:42 +0200 Subject: [PATCH 06/26] added table of contents --- easybuild/tools/docs.py | 15 +++------------ 1 file changed, 3 insertions(+), 12 deletions(-) diff --git a/easybuild/tools/docs.py b/easybuild/tools/docs.py index aa6cc45387..65d5b54270 100644 --- a/easybuild/tools/docs.py +++ b/easybuild/tools/docs.py @@ -164,7 +164,9 @@ def generic_easyblocks(): docs.append(doc_easyblock(eb_class)) seen.append(name) - return sorted(docs) + toc = ['.. contents:: Available generic easyblocks', ' :depth: 1', ''] + + return toc + sorted(docs) def doc_easyblock(eb_class): @@ -257,14 +259,3 @@ def mk_rst_table(titles, values): def backtick(string): return '``' + string + '``' - - - - - - - - - - - From 05bd7523e7df3b32396a92176346bea7e6154eca Mon Sep 17 00:00:00 2001 From: Caroline De Brouwer Date: Wed, 8 Jul 2015 10:52:02 +0200 Subject: [PATCH 07/26] Fixed some remarks --- :q | 275 ++++++++++++++++++++++++++++++++++++++++ easybuild/tools/docs.py | 43 +++---- 2 files changed, 296 insertions(+), 22 deletions(-) create mode 100644 :q diff --git a/:q b/:q new file mode 100644 index 0000000000..ee31281b3e --- /dev/null +++ b/:q @@ -0,0 +1,275 @@ +# # +# Copyright 2009-2015 Ghent University +# +# This file is part of EasyBuild, +# originally created by the HPC team of Ghent University (http://ugent.be/hpc/en), +# with support of Ghent University (http://ugent.be/hpc), +# the Flemish Supercomputer Centre (VSC) (https://vscentrum.be/nl/en), +# the Hercules foundation (http://www.herculesstichting.be/in_English) +# and the Department of Economy, Science and Innovation (EWI) (http://www.ewi-vlaanderen.be/en). +# +# http://github.com/hpcugent/easybuild +# +# EasyBuild is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation v2. +# +# EasyBuild is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with EasyBuild. If not, see . +# # +""" +Documentation-related functionality + +@author: Stijn De Weirdt (Ghent University) +@author: Dries Verdegem (Ghent University) +@author: Kenneth Hoste (Ghent University) +@author: Pieter De Baets (Ghent University) +@author: Jens Timmerman (Ghent University) +@author: Toon Willems (Ghent University) +@author: Ward Poelmans (Ghent University) +""" +import copy +import inspect +import os + +from easybuild.framework.easyconfig.default import DEFAULT_CONFIG, HIDDEN, sorted_categories +from easybuild.framework.easyconfig.easyconfig import get_easyblock_class +from easybuild.tools.ordereddict import OrderedDict +from easybuild.tools.utilities import quote_str, import_available_modules +from easybuild.tools.filetools import read_file + +FORMAT_RST = 'rst' +FORMAT_TXT = 'txt' + +def det_col_width(entries, title): + """Determine column width based on column title and list of entries.""" + return max(map(len, entries + [title])) + + +def avail_easyconfig_params_rst(title, grouped_params): + """ + Compose overview of available easyconfig parameters, in RST format. + """ + # main title + lines = [ + title, + '=' * len(title), + '', + ] + + for grpname in grouped_params: + # group section title + lines.append("%s parameters" % grpname) + lines.extend(['-' * len(lines[-1]), '']) + + titles = ["**Parameter name**", "**Description**", "**Default value**"] + values = [ + [backtick(name) for name in grouped_params[grpname].keys()], + [x[0] for x in grouped_params[grpname].values()], + [str(quote_str(x[1])) for x in grouped_params[grpname].values()] + ] + + lines.extend(mk_rst_table(titles, values)) + lines.append('') + + return '\n'.join(lines) + +def avail_easyconfig_params_txt(title, grouped_params): + """ + Compose overview of available easyconfig parameters, in plain text format. + """ + # main title + lines = [ + '%s:' % title, + '', + ] + + for grpname in grouped_params: + # group section title + lines.append(grpname.upper()) + lines.append('-' * len(lines[-1])) + + # determine width of 'name' column, to left-align descriptions + nw = max(map(len, grouped_params[grpname].keys())) + + # line by parameter + for name, (descr, dflt) in sorted(grouped_params[grpname].items()): + lines.append("{0:<{nw}} {1:} [default: {2:}]".format(name, descr, str(quote_str(dflt)), nw=nw)) + lines.append('') + + return '\n'.join(lines) + +def avail_easyconfig_params(easyblock, output_format): + """ + Compose overview of available easyconfig parameters, in specified format. + """ + params = copy.deepcopy(DEFAULT_CONFIG) + + # include list of extra parameters (if any) + extra_params = {} + app = get_easyblock_class(easyblock, default_fallback=False) + if app is not None: + extra_params = app.extra_options() + params.update(extra_params) + + # compose title + title = "Available easyconfig parameters" + if extra_params: + title += " (* indicates specific to the %s easyblock)" % app.__name__ + + # group parameters by category + grouped_params = OrderedDict() + for category in sorted_categories(): + # exclude hidden parameters + if category[1].upper() in [HIDDEN]: + continue + + grpname = category[1] + grouped_params[grpname] = {} + for name, (dflt, descr, cat) in params.items(): + if cat == category: + if name in extra_params: + # mark easyblock-specific parameters + name = '%s*' % name + grouped_params[grpname].update({name: (descr, dflt)}) + + if not grouped_params[grpname]: + del grouped_params[grpname] + + # compose output, according to specified format (txt, rst, ...) + avail_easyconfig_params_functions = { + FORMAT_RST: avail_easyconfig_params_rst, + FORMAT_TXT: avail_easyconfig_params_txt, + } + return avail_easyconfig_params_functions[output_format](title, grouped_params) + +def generic_easyblocks(): + """ + Compose overview of all generic easyblocks + """ + modules = import_available_modules('easybuild.easyblocks.generic') + docs = [] + seen = [] + + for m in modules: + for name,obj in inspect.getmembers(m, inspect.isclass): + eb_class = getattr(m, name) + # skip imported classes that are not easyblocks + if eb_class.__module__.startswith('easybuild.easyblocks.generic') and name not in seen: + docs.append(doc_easyblock(eb_class)) + seen.append(name) + + toc = ['.. contents:: Available generic easyblocks', ' :depth: 1', ''] + + return toc + sorted(docs) + +def overriden_functions(eb_class, parent_class): + print eb_class.__name__ + print eb_class + print parent_class + for func in eb_class.__dict__.keys(): + child_func = getattr(eb_class, func) + parent_func = getattr(parent_class, func) + if child_func.__func__ is not parent_func.__func__: + print func + + + +def doc_easyblock(eb_class): + """ + Compose overview of one easyblock given class object of the easyblock in rst format + """ + classname = eb_class.__name__ + + common_params = { + 'ConfigureMake' : ['configopts', 'buildopts', 'installopts'], + # to be continued + } + + lines = [ + '``' + classname + '``', + '=' * (len(classname)+4), + '', + ] + + bases = ['``' + base.__name__ + '``' for base in eb_class.__bases__] + derived = '(derives from ' + ', '.join(bases) + ')' + lines.extend([derived, '']) + + for base in eb_class.__bases__: + overriden_functions(eb_class, base) + + # Description (docstring) + lines.extend([eb_class.__doc__.strip(), '']) + + # Add extra options, if any + if eb_class.extra_options(): + extra_parameters = 'Extra easyconfig parameters specific to ' + backtick(classname) + ' easyblock' + lines.extend([extra_parameters, '-' * len(extra_parameters), '']) + ex_opt = eb_class.extra_options() + + titles = ['easyconfig parameter', 'description', 'default value'] + values = [[backtick(key) for key in ex_opt], [val[1] for val in ex_opt.values()], [backtick(str(quote_str(val[0]))) for val in ex_opt.values()]] + + lines.extend(mk_rst_table(titles, values)) + lines.append('') + + if classname in common_params: + commonly_used = 'Commonly used easyconfig parameters with ' + backtick(classname) + ' easyblock' + lines.extend([commonly_used, '-' * len(commonly_used)]) + + for opt in common_params[classname]: + param = '* ' + backtick(opt) + ' - ' + DEFAULT_CONFIG[opt][1] + lines.append(param) + + + if classname + '.eb' in os.listdir(os.path.join(os.path.dirname(__file__), 'doc_examples')): + lines.extend(['', 'Example', '-' * 8, '', '::', '']) + f = open(os.path.join(os.path.dirname(__file__), 'doc_examples', classname+'.eb'), "r") + for line in f.readlines(): + lines.append(' ' + line.strip()) + lines.append('') # empty line after literal block + + return '\n'.join(lines) + + +def mk_rst_table(titles, values): + """ + Returns an rst table with given titles and values (a nested list of string values for each column) + """ + num_col = len(titles) + table = [] + col_widths = [] + tmpl = [] + line= [] + + # figure out column widths + for i in range(0, num_col): + col_widths.append(det_col_width(values[i], titles[i])) + + # make line template + tmpl.append('{' + str(i) + ':{c}<' + str(col_widths[i]) + '}') + line.append('') # needed for table line + + line_tmpl = ' '.join(tmpl) + table_line = line_tmpl.format(*line, c="=") + + table.append(table_line) + table.append(line_tmpl.format(*titles, c=' ')) + table.append(table_line) + + for i in range(0, len(values[0])): + table.append(line_tmpl.format(*[v[i] for v in values], c=' ')) + + table.extend([table_line, '']) + + return table + + +def backtick(string): + return '``' + string + '``' diff --git a/easybuild/tools/docs.py b/easybuild/tools/docs.py index 65d5b54270..c2b84520b6 100644 --- a/easybuild/tools/docs.py +++ b/easybuild/tools/docs.py @@ -46,6 +46,11 @@ FORMAT_RST = 'rst' FORMAT_TXT = 'txt' +COMMON_PARAMS = { + 'ConfigureMake' : ['configopts', 'buildopts', 'installopts'], + # to be continued +} + def det_col_width(entries, title): """Determine column width based on column title and list of entries.""" return max(map(len, entries + [title])) @@ -69,7 +74,7 @@ def avail_easyconfig_params_rst(title, grouped_params): titles = ["**Parameter name**", "**Description**", "**Default value**"] values = [ - [backtick(name) for name in grouped_params[grpname].keys()], + ['``' + name + '``' for name in grouped_params[grpname].keys()], [x[0] for x in grouped_params[grpname].values()], [str(quote_str(x[1])) for x in grouped_params[grpname].values()] ] @@ -153,6 +158,7 @@ def generic_easyblocks(): Compose overview of all generic easyblocks """ modules = import_available_modules('easybuild.easyblocks.generic') + path_to_examples = os.path.join(os.path.dirname(__file__), 'doc_examples') #TODO: move them somewhere else docs = [] seen = [] @@ -161,25 +167,19 @@ def generic_easyblocks(): eb_class = getattr(m, name) # skip imported classes that are not easyblocks if eb_class.__module__.startswith('easybuild.easyblocks.generic') and name not in seen: - docs.append(doc_easyblock(eb_class)) + docs.append(doc_easyblock(eb_class, path_to_examples)) seen.append(name) toc = ['.. contents:: Available generic easyblocks', ' :depth: 1', ''] return toc + sorted(docs) - -def doc_easyblock(eb_class): +def doc_easyblock(eb_class, path_to_examples): """ Compose overview of one easyblock given class object of the easyblock in rst format """ classname = eb_class.__name__ - common_params = { - 'ConfigureMake' : ['configopts', 'buildopts', 'installopts'], - # to be continued - } - lines = [ '``' + classname + '``', '=' * (len(classname)+4), @@ -195,35 +195,37 @@ def doc_easyblock(eb_class): # Add extra options, if any if eb_class.extra_options(): - extra_parameters = 'Extra easyconfig parameters specific to ' + backtick(classname) + ' easyblock' + extra_parameters = 'Extra easyconfig parameters specific to ``' + classname + '`` easyblock' lines.extend([extra_parameters, '-' * len(extra_parameters), '']) ex_opt = eb_class.extra_options() titles = ['easyconfig parameter', 'description', 'default value'] - values = [[backtick(key) for key in ex_opt], [val[1] for val in ex_opt.values()], [backtick(str(quote_str(val[0]))) for val in ex_opt.values()]] + values = [ + ['``' + key + '``' for key in ex_opt], + [val[1] for val in ex_opt.values()], + ['``' + str(quote_str(val[0])) + '``' for val in ex_opt.values()] + ] lines.extend(mk_rst_table(titles, values)) lines.append('') - if classname in common_params: - commonly_used = 'Commonly used easyconfig parameters with ' + backtick(classname) + ' easyblock' + if classname in COMMON_PARAMS: + commonly_used = 'Commonly used easyconfig parameters with ``' + classname + '`` easyblock' lines.extend([commonly_used, '-' * len(commonly_used)]) - for opt in common_params[classname]: - param = '* ' + backtick(opt) + ' - ' + DEFAULT_CONFIG[opt][1] + for opt in COMMON_PARAMS[classname]: + param = '* ``' + opt + '`` - ' + DEFAULT_CONFIG[opt][1] lines.append(param) - if classname + '.eb' in os.listdir(os.path.join(os.path.dirname(__file__), 'doc_examples')): + if classname + '.eb' in os.listdir(os.path.join(path_to_examples)): lines.extend(['', 'Example', '-' * 8, '', '::', '']) - f = open(os.path.join(os.path.dirname(__file__), 'doc_examples', classname+'.eb'), "r") - for line in f.readlines(): + for line in read_file(os.path.join(path_to_examples, classname+'.eb')).split('\n'): lines.append(' ' + line.strip()) lines.append('') # empty line after literal block return '\n'.join(lines) - def mk_rst_table(titles, values): """ Returns an rst table with given titles and values (a nested list of string values for each column) @@ -256,6 +258,3 @@ def mk_rst_table(titles, values): return table - -def backtick(string): - return '``' + string + '``' From c657025791b533e7fb39ed61e70be0af946a3413 Mon Sep 17 00:00:00 2001 From: Caroline De Brouwer Date: Wed, 8 Jul 2015 10:52:51 +0200 Subject: [PATCH 08/26] Delete :q something went wrong there --- :q | 275 ------------------------------------------------------------- 1 file changed, 275 deletions(-) delete mode 100644 :q diff --git a/:q b/:q deleted file mode 100644 index ee31281b3e..0000000000 --- a/:q +++ /dev/null @@ -1,275 +0,0 @@ -# # -# Copyright 2009-2015 Ghent University -# -# This file is part of EasyBuild, -# originally created by the HPC team of Ghent University (http://ugent.be/hpc/en), -# with support of Ghent University (http://ugent.be/hpc), -# the Flemish Supercomputer Centre (VSC) (https://vscentrum.be/nl/en), -# the Hercules foundation (http://www.herculesstichting.be/in_English) -# and the Department of Economy, Science and Innovation (EWI) (http://www.ewi-vlaanderen.be/en). -# -# http://github.com/hpcugent/easybuild -# -# EasyBuild is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation v2. -# -# EasyBuild is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with EasyBuild. If not, see . -# # -""" -Documentation-related functionality - -@author: Stijn De Weirdt (Ghent University) -@author: Dries Verdegem (Ghent University) -@author: Kenneth Hoste (Ghent University) -@author: Pieter De Baets (Ghent University) -@author: Jens Timmerman (Ghent University) -@author: Toon Willems (Ghent University) -@author: Ward Poelmans (Ghent University) -""" -import copy -import inspect -import os - -from easybuild.framework.easyconfig.default import DEFAULT_CONFIG, HIDDEN, sorted_categories -from easybuild.framework.easyconfig.easyconfig import get_easyblock_class -from easybuild.tools.ordereddict import OrderedDict -from easybuild.tools.utilities import quote_str, import_available_modules -from easybuild.tools.filetools import read_file - -FORMAT_RST = 'rst' -FORMAT_TXT = 'txt' - -def det_col_width(entries, title): - """Determine column width based on column title and list of entries.""" - return max(map(len, entries + [title])) - - -def avail_easyconfig_params_rst(title, grouped_params): - """ - Compose overview of available easyconfig parameters, in RST format. - """ - # main title - lines = [ - title, - '=' * len(title), - '', - ] - - for grpname in grouped_params: - # group section title - lines.append("%s parameters" % grpname) - lines.extend(['-' * len(lines[-1]), '']) - - titles = ["**Parameter name**", "**Description**", "**Default value**"] - values = [ - [backtick(name) for name in grouped_params[grpname].keys()], - [x[0] for x in grouped_params[grpname].values()], - [str(quote_str(x[1])) for x in grouped_params[grpname].values()] - ] - - lines.extend(mk_rst_table(titles, values)) - lines.append('') - - return '\n'.join(lines) - -def avail_easyconfig_params_txt(title, grouped_params): - """ - Compose overview of available easyconfig parameters, in plain text format. - """ - # main title - lines = [ - '%s:' % title, - '', - ] - - for grpname in grouped_params: - # group section title - lines.append(grpname.upper()) - lines.append('-' * len(lines[-1])) - - # determine width of 'name' column, to left-align descriptions - nw = max(map(len, grouped_params[grpname].keys())) - - # line by parameter - for name, (descr, dflt) in sorted(grouped_params[grpname].items()): - lines.append("{0:<{nw}} {1:} [default: {2:}]".format(name, descr, str(quote_str(dflt)), nw=nw)) - lines.append('') - - return '\n'.join(lines) - -def avail_easyconfig_params(easyblock, output_format): - """ - Compose overview of available easyconfig parameters, in specified format. - """ - params = copy.deepcopy(DEFAULT_CONFIG) - - # include list of extra parameters (if any) - extra_params = {} - app = get_easyblock_class(easyblock, default_fallback=False) - if app is not None: - extra_params = app.extra_options() - params.update(extra_params) - - # compose title - title = "Available easyconfig parameters" - if extra_params: - title += " (* indicates specific to the %s easyblock)" % app.__name__ - - # group parameters by category - grouped_params = OrderedDict() - for category in sorted_categories(): - # exclude hidden parameters - if category[1].upper() in [HIDDEN]: - continue - - grpname = category[1] - grouped_params[grpname] = {} - for name, (dflt, descr, cat) in params.items(): - if cat == category: - if name in extra_params: - # mark easyblock-specific parameters - name = '%s*' % name - grouped_params[grpname].update({name: (descr, dflt)}) - - if not grouped_params[grpname]: - del grouped_params[grpname] - - # compose output, according to specified format (txt, rst, ...) - avail_easyconfig_params_functions = { - FORMAT_RST: avail_easyconfig_params_rst, - FORMAT_TXT: avail_easyconfig_params_txt, - } - return avail_easyconfig_params_functions[output_format](title, grouped_params) - -def generic_easyblocks(): - """ - Compose overview of all generic easyblocks - """ - modules = import_available_modules('easybuild.easyblocks.generic') - docs = [] - seen = [] - - for m in modules: - for name,obj in inspect.getmembers(m, inspect.isclass): - eb_class = getattr(m, name) - # skip imported classes that are not easyblocks - if eb_class.__module__.startswith('easybuild.easyblocks.generic') and name not in seen: - docs.append(doc_easyblock(eb_class)) - seen.append(name) - - toc = ['.. contents:: Available generic easyblocks', ' :depth: 1', ''] - - return toc + sorted(docs) - -def overriden_functions(eb_class, parent_class): - print eb_class.__name__ - print eb_class - print parent_class - for func in eb_class.__dict__.keys(): - child_func = getattr(eb_class, func) - parent_func = getattr(parent_class, func) - if child_func.__func__ is not parent_func.__func__: - print func - - - -def doc_easyblock(eb_class): - """ - Compose overview of one easyblock given class object of the easyblock in rst format - """ - classname = eb_class.__name__ - - common_params = { - 'ConfigureMake' : ['configopts', 'buildopts', 'installopts'], - # to be continued - } - - lines = [ - '``' + classname + '``', - '=' * (len(classname)+4), - '', - ] - - bases = ['``' + base.__name__ + '``' for base in eb_class.__bases__] - derived = '(derives from ' + ', '.join(bases) + ')' - lines.extend([derived, '']) - - for base in eb_class.__bases__: - overriden_functions(eb_class, base) - - # Description (docstring) - lines.extend([eb_class.__doc__.strip(), '']) - - # Add extra options, if any - if eb_class.extra_options(): - extra_parameters = 'Extra easyconfig parameters specific to ' + backtick(classname) + ' easyblock' - lines.extend([extra_parameters, '-' * len(extra_parameters), '']) - ex_opt = eb_class.extra_options() - - titles = ['easyconfig parameter', 'description', 'default value'] - values = [[backtick(key) for key in ex_opt], [val[1] for val in ex_opt.values()], [backtick(str(quote_str(val[0]))) for val in ex_opt.values()]] - - lines.extend(mk_rst_table(titles, values)) - lines.append('') - - if classname in common_params: - commonly_used = 'Commonly used easyconfig parameters with ' + backtick(classname) + ' easyblock' - lines.extend([commonly_used, '-' * len(commonly_used)]) - - for opt in common_params[classname]: - param = '* ' + backtick(opt) + ' - ' + DEFAULT_CONFIG[opt][1] - lines.append(param) - - - if classname + '.eb' in os.listdir(os.path.join(os.path.dirname(__file__), 'doc_examples')): - lines.extend(['', 'Example', '-' * 8, '', '::', '']) - f = open(os.path.join(os.path.dirname(__file__), 'doc_examples', classname+'.eb'), "r") - for line in f.readlines(): - lines.append(' ' + line.strip()) - lines.append('') # empty line after literal block - - return '\n'.join(lines) - - -def mk_rst_table(titles, values): - """ - Returns an rst table with given titles and values (a nested list of string values for each column) - """ - num_col = len(titles) - table = [] - col_widths = [] - tmpl = [] - line= [] - - # figure out column widths - for i in range(0, num_col): - col_widths.append(det_col_width(values[i], titles[i])) - - # make line template - tmpl.append('{' + str(i) + ':{c}<' + str(col_widths[i]) + '}') - line.append('') # needed for table line - - line_tmpl = ' '.join(tmpl) - table_line = line_tmpl.format(*line, c="=") - - table.append(table_line) - table.append(line_tmpl.format(*titles, c=' ')) - table.append(table_line) - - for i in range(0, len(values[0])): - table.append(line_tmpl.format(*[v[i] for v in values], c=' ')) - - table.extend([table_line, '']) - - return table - - -def backtick(string): - return '``' + string + '``' From cc8da015350afce5f2dd4fbfaf4f211baaf7a020 Mon Sep 17 00:00:00 2001 From: Caroline De Brouwer Date: Wed, 8 Jul 2015 15:11:38 +0200 Subject: [PATCH 09/26] added custom step functions to doc --- easybuild/tools/docs.py | 37 ++++++++++++++++++++++++------------- 1 file changed, 24 insertions(+), 13 deletions(-) diff --git a/easybuild/tools/docs.py b/easybuild/tools/docs.py index c2b84520b6..27df95800d 100644 --- a/easybuild/tools/docs.py +++ b/easybuild/tools/docs.py @@ -46,11 +46,6 @@ FORMAT_RST = 'rst' FORMAT_TXT = 'txt' -COMMON_PARAMS = { - 'ConfigureMake' : ['configopts', 'buildopts', 'installopts'], - # to be continued -} - def det_col_width(entries, title): """Determine column width based on column title and list of entries.""" return max(map(len, entries + [title])) @@ -153,12 +148,11 @@ def avail_easyconfig_params(easyblock, output_format): } return avail_easyconfig_params_functions[output_format](title, grouped_params) -def generic_easyblocks(): +def generic_easyblocks(path_to_examples, common_params={}, doc_functions=[]): """ Compose overview of all generic easyblocks """ modules = import_available_modules('easybuild.easyblocks.generic') - path_to_examples = os.path.join(os.path.dirname(__file__), 'doc_examples') #TODO: move them somewhere else docs = [] seen = [] @@ -167,14 +161,14 @@ def generic_easyblocks(): eb_class = getattr(m, name) # skip imported classes that are not easyblocks if eb_class.__module__.startswith('easybuild.easyblocks.generic') and name not in seen: - docs.append(doc_easyblock(eb_class, path_to_examples)) + docs.append(doc_easyblock(eb_class, path_to_examples, common_params, doc_functions)) seen.append(name) toc = ['.. contents:: Available generic easyblocks', ' :depth: 1', ''] return toc + sorted(docs) -def doc_easyblock(eb_class, path_to_examples): +def doc_easyblock(eb_class, path_to_examples, common_params, doc_functions): """ Compose overview of one easyblock given class object of the easyblock in rst format """ @@ -207,17 +201,34 @@ def doc_easyblock(eb_class, path_to_examples): ] lines.extend(mk_rst_table(titles, values)) - lines.append('') - if classname in COMMON_PARAMS: + # Add commonly used parameters + if classname in common_params: commonly_used = 'Commonly used easyconfig parameters with ``' + classname + '`` easyblock' lines.extend([commonly_used, '-' * len(commonly_used)]) - for opt in COMMON_PARAMS[classname]: + for opt in common_params[classname]: param = '* ``' + opt + '`` - ' + DEFAULT_CONFIG[opt][1] lines.append(param) + lines.append('') + + custom = [] + # Add docstring for custom steps + for func in doc_functions: + if func in eb_class.__dict__: + f = eb_class.__dict__[func] + elif func in eb_class.__bases__[0].__dict__: + f = eb_class.__bases__[0].__dict__[func] + + if f.__doc__: + custom.append('* ``' + func + '`` - ' + f.__doc__.strip()) + + if custom: + title = 'Customised steps' + lines.extend([title, '-' * len(title)] + custom) + lines.append('') - + # Add example if available if classname + '.eb' in os.listdir(os.path.join(path_to_examples)): lines.extend(['', 'Example', '-' * 8, '', '::', '']) for line in read_file(os.path.join(path_to_examples, classname+'.eb')).split('\n'): From 09a974276f271f49b94220d29d7a1371848dc735 Mon Sep 17 00:00:00 2001 From: Caroline De Brouwer Date: Wed, 8 Jul 2015 15:22:32 +0200 Subject: [PATCH 10/26] remove examples from framework --- easybuild/tools/doc_examples/Binary.eb | 21 ------------ easybuild/tools/doc_examples/Bundle.eb | 17 ---------- easybuild/tools/doc_examples/CMakeMake.eb | 30 ----------------- easybuild/tools/doc_examples/ConfigureMake.eb | 20 ----------- .../ConfigureMakePythonPackage.eb | 33 ------------------- 5 files changed, 121 deletions(-) delete mode 100644 easybuild/tools/doc_examples/Binary.eb delete mode 100644 easybuild/tools/doc_examples/Bundle.eb delete mode 100644 easybuild/tools/doc_examples/CMakeMake.eb delete mode 100644 easybuild/tools/doc_examples/ConfigureMake.eb delete mode 100644 easybuild/tools/doc_examples/ConfigureMakePythonPackage.eb diff --git a/easybuild/tools/doc_examples/Binary.eb b/easybuild/tools/doc_examples/Binary.eb deleted file mode 100644 index 2fa31617c3..0000000000 --- a/easybuild/tools/doc_examples/Binary.eb +++ /dev/null @@ -1,21 +0,0 @@ -easyblock = 'Binary' - -name = 'Platanus' -version = '1.2.1' -versionsuffix = '-linux-x86_64' - -homepage = 'http://platanus.bio.titech.ac.jp/' -description = """PLATform for Assembling NUcleotide Sequences""" - -toolchain = {'name': 'dummy', 'version': 'dummy'} - -source_urls = ['http://platanus.bio.titech.ac.jp/Platanus_release/20130901010201'] -sources = ['platanus'] -checksums = ['02cf92847ec704d010a54df293b9c60a'] - -sanity_check_paths = { - 'files': ['platanus'], - 'dirs': [], -} - -moduleclass = 'bio' diff --git a/easybuild/tools/doc_examples/Bundle.eb b/easybuild/tools/doc_examples/Bundle.eb deleted file mode 100644 index 067ccdbe63..0000000000 --- a/easybuild/tools/doc_examples/Bundle.eb +++ /dev/null @@ -1,17 +0,0 @@ -easyblock = 'Bundle' - -name = 'Autotools' -version = '20150119' # date of the most recent change - -homepage = 'http://autotools.io' -description = """This bundle collect the standard GNU build tools: Autoconf, Automake and libtool""" - -toolchain = {'name': 'GCC', 'version': '4.9.2'} - -dependencies = [ - ('Autoconf', '2.69'), # 20120424 - ('Automake', '1.15'), # 20150105 - ('libtool', '2.4.5'), # 20150119 -] - -moduleclass = 'devel' diff --git a/easybuild/tools/doc_examples/CMakeMake.eb b/easybuild/tools/doc_examples/CMakeMake.eb deleted file mode 100644 index 1e8a2bf6f6..0000000000 --- a/easybuild/tools/doc_examples/CMakeMake.eb +++ /dev/null @@ -1,30 +0,0 @@ -easyblock = 'CMakeMake' - -name = 'ANTs' -version = '2.1.0rc3' - -homepage = 'http://stnava.github.io/ANTs/' -description = """ANTs extracts information from complex datasets that include imaging. ANTs is useful for managing, - interpreting and visualizing multidimensional data.""" - -toolchain = {'name': 'goolf', 'version': '1.5.14'} -toolchainopts = {'pic': True} - -source_urls = ['https://github.com/stnava/ANTs/archive/'] -sources = ['v%(version)s.tar.gz'] - -builddependencies = [('CMake', '3.0.2')] - -skipsteps = ['install'] -buildopts = ' && mkdir -p %(installdir)s && cp -r * %(installdir)s/' - -parallel = 1 - -separate_build_dir = True - -sanity_check_paths = { - 'files': ['bin/ANTS'], - 'dirs': ['lib'], -} - -moduleclass = 'data' diff --git a/easybuild/tools/doc_examples/ConfigureMake.eb b/easybuild/tools/doc_examples/ConfigureMake.eb deleted file mode 100644 index 9a0d4bf65e..0000000000 --- a/easybuild/tools/doc_examples/ConfigureMake.eb +++ /dev/null @@ -1,20 +0,0 @@ -easyblock = 'ConfigureMake' - -name = 'zsync' -version = '0.6.2' - -homepage = 'http://zsync.moria.org.uk/' -description = """zsync-0.6.2: Optimising file distribution program, a 1-to-many rsync""" - -sources = [SOURCE_TAR_BZ2] -source_urls = ['http://zsync.moria.org.uk/download/'] - - -toolchain = {'name': 'ictce', 'version': '5.3.0'} - -sanity_check_paths = { - 'files': ['bin/zsync'], - 'dirs': [] - } - -moduleclass = 'tools' diff --git a/easybuild/tools/doc_examples/ConfigureMakePythonPackage.eb b/easybuild/tools/doc_examples/ConfigureMakePythonPackage.eb deleted file mode 100644 index 0f9fd09a84..0000000000 --- a/easybuild/tools/doc_examples/ConfigureMakePythonPackage.eb +++ /dev/null @@ -1,33 +0,0 @@ -easyblock = 'ConfigureMakePythonPackage' - -name = 'PyQt' -version = '4.11.3' - -homepage = 'http://www.riverbankcomputing.co.uk/software/pyqt' -description = """PyQt is a set of Python v2 and v3 bindings for Digia's Qt application framework.""" - -toolchain = {'name': 'goolf', 'version': '1.5.14'} - -sources = ['%(name)s-x11-gpl-%(version)s.tar.gz'] -source_urls = ['http://sourceforge.net/projects/pyqt/files/PyQt4/PyQt-%(version)s'] - -python = 'Python' -pyver = '2.7.9' -pythonshortver = '.'.join(pyver.split('.')[:2]) -versionsuffix = '-%s-%s' % (python, pyver) - -dependencies = [ - (python, pyver), - ('SIP', '4.16.4', versionsuffix), - ('Qt', '4.8.6'), -] - -configopts = "configure-ng.py --confirm-license" -configopts += " --destdir=%%(installdir)s/lib/python%s/site-packages " % pythonshortver -configopts += " --no-sip-files" - -options = {'modulename': 'PyQt4'} - -modextrapaths = {'PYTHONPATH': 'lib/python%s/site-packages' % pythonshortver} - -moduleclass = 'vis' From 0299605b9adc9629d613abd5f2389c7c5eac2e41 Mon Sep 17 00:00:00 2001 From: Caroline De Brouwer Date: Wed, 8 Jul 2015 16:25:53 +0200 Subject: [PATCH 11/26] added internal references for parent classes --- easybuild/tools/docs.py | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/easybuild/tools/docs.py b/easybuild/tools/docs.py index 27df95800d..f1d7c4b923 100644 --- a/easybuild/tools/docs.py +++ b/easybuild/tools/docs.py @@ -154,21 +154,24 @@ def generic_easyblocks(path_to_examples, common_params={}, doc_functions=[]): """ modules = import_available_modules('easybuild.easyblocks.generic') docs = [] - seen = [] + all_blocks = [] + # get all blocks for m in modules: for name,obj in inspect.getmembers(m, inspect.isclass): eb_class = getattr(m, name) # skip imported classes that are not easyblocks - if eb_class.__module__.startswith('easybuild.easyblocks.generic') and name not in seen: - docs.append(doc_easyblock(eb_class, path_to_examples, common_params, doc_functions)) - seen.append(name) + if eb_class.__module__.startswith('easybuild.easyblocks.generic') and eb_class not in all_blocks: + all_blocks.append(eb_class) + + for eb_class in all_blocks: + docs.append(doc_easyblock(eb_class, path_to_examples, common_params, doc_functions, all_blocks)) toc = ['.. contents:: Available generic easyblocks', ' :depth: 1', ''] return toc + sorted(docs) -def doc_easyblock(eb_class, path_to_examples, common_params, doc_functions): +def doc_easyblock(eb_class, path_to_examples, common_params, doc_functions, all_blocks): """ Compose overview of one easyblock given class object of the easyblock in rst format """ @@ -180,7 +183,11 @@ def doc_easyblock(eb_class, path_to_examples, common_params, doc_functions): '', ] - bases = ['``' + base.__name__ + '``' for base in eb_class.__bases__] + bases = [] + for b in eb_class.__bases__: + base = b.__name__ + '_' if b in all_blocks else b.__name__ + bases.append(base) + derived = '(derives from ' + ', '.join(bases) + ')' lines.extend([derived, '']) From 5baa702ae48053eded2faa16b0dded1a6a9315a7 Mon Sep 17 00:00:00 2001 From: Caroline De Brouwer Date: Wed, 8 Jul 2015 16:32:49 +0200 Subject: [PATCH 12/26] added mark for inherited functions --- easybuild/tools/docs.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/easybuild/tools/docs.py b/easybuild/tools/docs.py index f1d7c4b923..734e97f549 100644 --- a/easybuild/tools/docs.py +++ b/easybuild/tools/docs.py @@ -219,16 +219,18 @@ def doc_easyblock(eb_class, path_to_examples, common_params, doc_functions, all_ lines.append(param) lines.append('') - custom = [] # Add docstring for custom steps + custom = [] + inh = '' for func in doc_functions: if func in eb_class.__dict__: f = eb_class.__dict__[func] elif func in eb_class.__bases__[0].__dict__: f = eb_class.__bases__[0].__dict__[func] + inh = ' (inherited)' if f.__doc__: - custom.append('* ``' + func + '`` - ' + f.__doc__.strip()) + custom.append('* ``' + func + '`` - ' + f.__doc__.strip() + inh) if custom: title = 'Customised steps' From 1e35b4295f586527bc609020d3d5fc0adf7668c5 Mon Sep 17 00:00:00 2001 From: Caroline De Brouwer Date: Wed, 8 Jul 2015 16:44:46 +0200 Subject: [PATCH 13/26] added page title --- easybuild/tools/docs.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/easybuild/tools/docs.py b/easybuild/tools/docs.py index 734e97f549..8260b31bf9 100644 --- a/easybuild/tools/docs.py +++ b/easybuild/tools/docs.py @@ -167,9 +167,10 @@ def generic_easyblocks(path_to_examples, common_params={}, doc_functions=[]): for eb_class in all_blocks: docs.append(doc_easyblock(eb_class, path_to_examples, common_params, doc_functions, all_blocks)) - toc = ['.. contents:: Available generic easyblocks', ' :depth: 1', ''] + title = 'Overview of generic easyblocks' - return toc + sorted(docs) + heading = ['=' * len(title), title, '=' * len(title), '', '.. contents:: Available generic easyblocks', ' :depth: 1', ''] + return heading + sorted(docs) def doc_easyblock(eb_class, path_to_examples, common_params, doc_functions, all_blocks): """ From 09c21da2e228fe402c2b69eef51076da7d8d40ec Mon Sep 17 00:00:00 2001 From: Caroline De Brouwer Date: Wed, 8 Jul 2015 16:56:24 +0200 Subject: [PATCH 14/26] Small fixes --- easybuild/tools/docs.py | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/easybuild/tools/docs.py b/easybuild/tools/docs.py index 8260b31bf9..e9824cee4c 100644 --- a/easybuild/tools/docs.py +++ b/easybuild/tools/docs.py @@ -43,9 +43,11 @@ from easybuild.tools.utilities import quote_str, import_available_modules from easybuild.tools.filetools import read_file + FORMAT_RST = 'rst' FORMAT_TXT = 'txt' + def det_col_width(entries, title): """Determine column width based on column title and list of entries.""" return max(map(len, entries + [title])) @@ -69,9 +71,9 @@ def avail_easyconfig_params_rst(title, grouped_params): titles = ["**Parameter name**", "**Description**", "**Default value**"] values = [ - ['``' + name + '``' for name in grouped_params[grpname].keys()], - [x[0] for x in grouped_params[grpname].values()], - [str(quote_str(x[1])) for x in grouped_params[grpname].values()] + ['``' + name + '``' for name in grouped_params[grpname].keys()], # parameter name + [x[0] for x in grouped_params[grpname].values()], # description + [str(quote_str(x[1])) for x in grouped_params[grpname].values()] #default value ] lines.extend(mk_rst_table(titles, values)) @@ -148,9 +150,10 @@ def avail_easyconfig_params(easyblock, output_format): } return avail_easyconfig_params_functions[output_format](title, grouped_params) -def generic_easyblocks(path_to_examples, common_params={}, doc_functions=[]): + +def gen_easyblocks_overview_rst(path_to_examples, common_params={}, doc_functions=[]): """ - Compose overview of all generic easyblocks + Compose overview of all generic easyblocks in rst format """ modules = import_available_modules('easybuild.easyblocks.generic') docs = [] @@ -165,14 +168,14 @@ def generic_easyblocks(path_to_examples, common_params={}, doc_functions=[]): all_blocks.append(eb_class) for eb_class in all_blocks: - docs.append(doc_easyblock(eb_class, path_to_examples, common_params, doc_functions, all_blocks)) + docs.append(gen_easyblock_doc_section_rst(eb_class, path_to_examples, common_params, doc_functions, all_blocks)) title = 'Overview of generic easyblocks' - heading = ['=' * len(title), title, '=' * len(title), '', '.. contents:: Available generic easyblocks', ' :depth: 1', ''] + heading = ['=' * len(title), title, '=' * len(title), '', '.. contents::', ' :depth: 1', ''] return heading + sorted(docs) -def doc_easyblock(eb_class, path_to_examples, common_params, doc_functions, all_blocks): +def gen_easyblock_doc_section_rst(eb_class, path_to_examples, common_params, doc_functions, all_blocks): """ Compose overview of one easyblock given class object of the easyblock in rst format """ @@ -203,9 +206,9 @@ def doc_easyblock(eb_class, path_to_examples, common_params, doc_functions, all_ titles = ['easyconfig parameter', 'description', 'default value'] values = [ - ['``' + key + '``' for key in ex_opt], - [val[1] for val in ex_opt.values()], - ['``' + str(quote_str(val[0])) + '``' for val in ex_opt.values()] + ['``' + key + '``' for key in ex_opt], # parameter name + [val[1] for val in ex_opt.values()], # description + ['``' + str(quote_str(val[0])) + '``' for val in ex_opt.values()] # default value ] lines.extend(mk_rst_table(titles, values)) From d05cd3025175003d972f75dc26d8a8c7c3d15e7f Mon Sep 17 00:00:00 2001 From: Caroline De Brouwer Date: Thu, 9 Jul 2015 09:22:18 +0200 Subject: [PATCH 15/26] More fixes --- easybuild/tools/docs.py | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/easybuild/tools/docs.py b/easybuild/tools/docs.py index e9824cee4c..ba406ffb29 100644 --- a/easybuild/tools/docs.py +++ b/easybuild/tools/docs.py @@ -182,6 +182,8 @@ def gen_easyblock_doc_section_rst(eb_class, path_to_examples, common_params, doc classname = eb_class.__name__ lines = [ + '.. ' + classname + ':', + '', '``' + classname + '``', '=' * (len(classname)+4), '', @@ -189,7 +191,7 @@ def gen_easyblock_doc_section_rst(eb_class, path_to_examples, common_params, doc bases = [] for b in eb_class.__bases__: - base = b.__name__ + '_' if b in all_blocks else b.__name__ + base = ':ref:`' + b.__name__ +'`' if b in all_blocks else b.__name__ bases.append(base) derived = '(derives from ' + ', '.join(bases) + ')' @@ -237,19 +239,21 @@ def gen_easyblock_doc_section_rst(eb_class, path_to_examples, common_params, doc custom.append('* ``' + func + '`` - ' + f.__doc__.strip() + inh) if custom: - title = 'Customised steps' + title = 'Customised steps in ``' + classname + '`` easyblock' lines.extend([title, '-' * len(title)] + custom) lines.append('') # Add example if available - if classname + '.eb' in os.listdir(os.path.join(path_to_examples)): - lines.extend(['', 'Example', '-' * 8, '', '::', '']) + if os.path.exists(os.path.join(path_to_examples, '%s.eb' % classname)): + title = 'Example for ``' + classname + '`` easyblock' + lines.extend(['', title, '-' * len(title), '', '::', '']) for line in read_file(os.path.join(path_to_examples, classname+'.eb')).split('\n'): lines.append(' ' + line.strip()) lines.append('') # empty line after literal block return '\n'.join(lines) + def mk_rst_table(titles, values): """ Returns an rst table with given titles and values (a nested list of string values for each column) @@ -281,4 +285,3 @@ def mk_rst_table(titles, values): table.extend([table_line, '']) return table - From 5062e0a43ed4f37f1bc197e778d7c1a8cc5ae1b1 Mon Sep 17 00:00:00 2001 From: Caroline De Brouwer Date: Thu, 9 Jul 2015 11:32:17 +0200 Subject: [PATCH 16/26] Small rst_table unit test --- doc_examples/Binary.eb | 21 +++++++ doc_examples/Bundle.eb | 17 ++++++ doc_examples/CMakeMake.eb | 30 ++++++++++ doc_examples/ConfigureMake.eb | 20 +++++++ doc_examples/ConfigureMakePythonPackage.eb | 33 +++++++++++ easybuild/tools/docs.py | 1 - test/framework/docs.py | 65 ++++++++++++++++++++++ test/framework/suite.py | 3 +- 8 files changed, 188 insertions(+), 2 deletions(-) create mode 100644 doc_examples/Binary.eb create mode 100644 doc_examples/Bundle.eb create mode 100644 doc_examples/CMakeMake.eb create mode 100644 doc_examples/ConfigureMake.eb create mode 100644 doc_examples/ConfigureMakePythonPackage.eb create mode 100644 test/framework/docs.py diff --git a/doc_examples/Binary.eb b/doc_examples/Binary.eb new file mode 100644 index 0000000000..2fa31617c3 --- /dev/null +++ b/doc_examples/Binary.eb @@ -0,0 +1,21 @@ +easyblock = 'Binary' + +name = 'Platanus' +version = '1.2.1' +versionsuffix = '-linux-x86_64' + +homepage = 'http://platanus.bio.titech.ac.jp/' +description = """PLATform for Assembling NUcleotide Sequences""" + +toolchain = {'name': 'dummy', 'version': 'dummy'} + +source_urls = ['http://platanus.bio.titech.ac.jp/Platanus_release/20130901010201'] +sources = ['platanus'] +checksums = ['02cf92847ec704d010a54df293b9c60a'] + +sanity_check_paths = { + 'files': ['platanus'], + 'dirs': [], +} + +moduleclass = 'bio' diff --git a/doc_examples/Bundle.eb b/doc_examples/Bundle.eb new file mode 100644 index 0000000000..067ccdbe63 --- /dev/null +++ b/doc_examples/Bundle.eb @@ -0,0 +1,17 @@ +easyblock = 'Bundle' + +name = 'Autotools' +version = '20150119' # date of the most recent change + +homepage = 'http://autotools.io' +description = """This bundle collect the standard GNU build tools: Autoconf, Automake and libtool""" + +toolchain = {'name': 'GCC', 'version': '4.9.2'} + +dependencies = [ + ('Autoconf', '2.69'), # 20120424 + ('Automake', '1.15'), # 20150105 + ('libtool', '2.4.5'), # 20150119 +] + +moduleclass = 'devel' diff --git a/doc_examples/CMakeMake.eb b/doc_examples/CMakeMake.eb new file mode 100644 index 0000000000..1e8a2bf6f6 --- /dev/null +++ b/doc_examples/CMakeMake.eb @@ -0,0 +1,30 @@ +easyblock = 'CMakeMake' + +name = 'ANTs' +version = '2.1.0rc3' + +homepage = 'http://stnava.github.io/ANTs/' +description = """ANTs extracts information from complex datasets that include imaging. ANTs is useful for managing, + interpreting and visualizing multidimensional data.""" + +toolchain = {'name': 'goolf', 'version': '1.5.14'} +toolchainopts = {'pic': True} + +source_urls = ['https://github.com/stnava/ANTs/archive/'] +sources = ['v%(version)s.tar.gz'] + +builddependencies = [('CMake', '3.0.2')] + +skipsteps = ['install'] +buildopts = ' && mkdir -p %(installdir)s && cp -r * %(installdir)s/' + +parallel = 1 + +separate_build_dir = True + +sanity_check_paths = { + 'files': ['bin/ANTS'], + 'dirs': ['lib'], +} + +moduleclass = 'data' diff --git a/doc_examples/ConfigureMake.eb b/doc_examples/ConfigureMake.eb new file mode 100644 index 0000000000..9a0d4bf65e --- /dev/null +++ b/doc_examples/ConfigureMake.eb @@ -0,0 +1,20 @@ +easyblock = 'ConfigureMake' + +name = 'zsync' +version = '0.6.2' + +homepage = 'http://zsync.moria.org.uk/' +description = """zsync-0.6.2: Optimising file distribution program, a 1-to-many rsync""" + +sources = [SOURCE_TAR_BZ2] +source_urls = ['http://zsync.moria.org.uk/download/'] + + +toolchain = {'name': 'ictce', 'version': '5.3.0'} + +sanity_check_paths = { + 'files': ['bin/zsync'], + 'dirs': [] + } + +moduleclass = 'tools' diff --git a/doc_examples/ConfigureMakePythonPackage.eb b/doc_examples/ConfigureMakePythonPackage.eb new file mode 100644 index 0000000000..0f9fd09a84 --- /dev/null +++ b/doc_examples/ConfigureMakePythonPackage.eb @@ -0,0 +1,33 @@ +easyblock = 'ConfigureMakePythonPackage' + +name = 'PyQt' +version = '4.11.3' + +homepage = 'http://www.riverbankcomputing.co.uk/software/pyqt' +description = """PyQt is a set of Python v2 and v3 bindings for Digia's Qt application framework.""" + +toolchain = {'name': 'goolf', 'version': '1.5.14'} + +sources = ['%(name)s-x11-gpl-%(version)s.tar.gz'] +source_urls = ['http://sourceforge.net/projects/pyqt/files/PyQt4/PyQt-%(version)s'] + +python = 'Python' +pyver = '2.7.9' +pythonshortver = '.'.join(pyver.split('.')[:2]) +versionsuffix = '-%s-%s' % (python, pyver) + +dependencies = [ + (python, pyver), + ('SIP', '4.16.4', versionsuffix), + ('Qt', '4.8.6'), +] + +configopts = "configure-ng.py --confirm-license" +configopts += " --destdir=%%(installdir)s/lib/python%s/site-packages " % pythonshortver +configopts += " --no-sip-files" + +options = {'modulename': 'PyQt4'} + +modextrapaths = {'PYTHONPATH': 'lib/python%s/site-packages' % pythonshortver} + +moduleclass = 'vis' diff --git a/easybuild/tools/docs.py b/easybuild/tools/docs.py index ba406ffb29..dd94257a94 100644 --- a/easybuild/tools/docs.py +++ b/easybuild/tools/docs.py @@ -183,7 +183,6 @@ def gen_easyblock_doc_section_rst(eb_class, path_to_examples, common_params, doc lines = [ '.. ' + classname + ':', - '', '``' + classname + '``', '=' * (len(classname)+4), '', diff --git a/test/framework/docs.py b/test/framework/docs.py new file mode 100644 index 0000000000..36f0d997f0 --- /dev/null +++ b/test/framework/docs.py @@ -0,0 +1,65 @@ +# # +# Copyright 2012-2015 Ghent University +# +# This file is part of EasyBuild, +# originally created by the HPC team of Ghent University (http://ugent.be/hpc/en), +# with support of Ghent University (http://ugent.be/hpc), +# the Flemish Supercomputer Centre (VSC) (https://vscentrum.be/nl/en), +# the Hercules foundation (http://www.herculesstichting.be/in_English) +# and the Department of Economy, Science and Innovation (EWI) (http://www.ewi-vlaanderen.be/en). +# +# http://github.com/hpcugent/easybuild +# +# EasyBuild is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation v2. +# +# EasyBuild is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with EasyBuild. If not, see . +## +""" +Unit tests for docs.py. +""" + +from test.framework.utilities import EnhancedTestCase, init_config +from unittest import TestLoader, main +from easybuild.tools.docs import mk_rst_table + +class DocsTest(EnhancedTestCase): + + def test_rst_table(self): + """ Test mk_rst_table function """ + entries_1 = [['one', 'two', 'three']] + t1 = 'This title is long' + titles_1 = [t1] + + # small table + table_1 = '\n'.join(mk_rst_table(titles_1, entries_1)) + check_1 = '\n'.join([ + '=' * len(t1), + t1, + '=' * len(t1), + 'one' + ' ' * (len(t1) - 3), + 'two' + ' ' * (len(t1) -3), + 'three' + ' ' * (len(t1) - 5), + '=' * len(t1), + '', + ]) + + self.assertEqual(table_1, check_1) + + +def suite(): + """ returns all test cases in this module """ + return TestLoader().loadTestsFromTestCase(DocsTest) + +if __name__ == '__main__': + # also check the setUp for debug + # logToScreen(enable=True) + # setLogLevelDebug() + main() diff --git a/test/framework/suite.py b/test/framework/suite.py index 2b6001221f..447aa9ca9f 100644 --- a/test/framework/suite.py +++ b/test/framework/suite.py @@ -62,6 +62,7 @@ import test.framework.easyconfigformat as ef import test.framework.ebconfigobj as ebco import test.framework.easyconfigversion as ev +import test.framework.docs as d import test.framework.filetools as f import test.framework.format_convert as f_c import test.framework.general as gen @@ -100,7 +101,7 @@ # call suite() for each module and then run them all # note: make sure the options unit tests run first, to avoid running some of them with a readily initialized config -tests = [gen, bl, o, r, ef, ev, ebco, ep, e, mg, m, mt, f, run, a, robot, b, v, g, tcv, tc, t, c, s, l, f_c, sc, tw, p] +tests = [gen, bl, o, r, ef, ev, ebco, ep, e, mg, m, mt, f, run, a, robot, b, v, g, tcv, tc, t, c, s, l, f_c, sc, tw, p, d] SUITE = unittest.TestSuite([x.suite() for x in tests]) From bf4936988c8d590d0d4c5206a08fad8bece26a9b Mon Sep 17 00:00:00 2001 From: Caroline De Brouwer Date: Thu, 9 Jul 2015 15:21:22 +0200 Subject: [PATCH 17/26] remove example files --- doc_examples/Binary.eb | 21 -------------- doc_examples/Bundle.eb | 17 ----------- doc_examples/CMakeMake.eb | 30 -------------------- doc_examples/ConfigureMake.eb | 20 ------------- doc_examples/ConfigureMakePythonPackage.eb | 33 ---------------------- 5 files changed, 121 deletions(-) delete mode 100644 doc_examples/Binary.eb delete mode 100644 doc_examples/Bundle.eb delete mode 100644 doc_examples/CMakeMake.eb delete mode 100644 doc_examples/ConfigureMake.eb delete mode 100644 doc_examples/ConfigureMakePythonPackage.eb diff --git a/doc_examples/Binary.eb b/doc_examples/Binary.eb deleted file mode 100644 index 2fa31617c3..0000000000 --- a/doc_examples/Binary.eb +++ /dev/null @@ -1,21 +0,0 @@ -easyblock = 'Binary' - -name = 'Platanus' -version = '1.2.1' -versionsuffix = '-linux-x86_64' - -homepage = 'http://platanus.bio.titech.ac.jp/' -description = """PLATform for Assembling NUcleotide Sequences""" - -toolchain = {'name': 'dummy', 'version': 'dummy'} - -source_urls = ['http://platanus.bio.titech.ac.jp/Platanus_release/20130901010201'] -sources = ['platanus'] -checksums = ['02cf92847ec704d010a54df293b9c60a'] - -sanity_check_paths = { - 'files': ['platanus'], - 'dirs': [], -} - -moduleclass = 'bio' diff --git a/doc_examples/Bundle.eb b/doc_examples/Bundle.eb deleted file mode 100644 index 067ccdbe63..0000000000 --- a/doc_examples/Bundle.eb +++ /dev/null @@ -1,17 +0,0 @@ -easyblock = 'Bundle' - -name = 'Autotools' -version = '20150119' # date of the most recent change - -homepage = 'http://autotools.io' -description = """This bundle collect the standard GNU build tools: Autoconf, Automake and libtool""" - -toolchain = {'name': 'GCC', 'version': '4.9.2'} - -dependencies = [ - ('Autoconf', '2.69'), # 20120424 - ('Automake', '1.15'), # 20150105 - ('libtool', '2.4.5'), # 20150119 -] - -moduleclass = 'devel' diff --git a/doc_examples/CMakeMake.eb b/doc_examples/CMakeMake.eb deleted file mode 100644 index 1e8a2bf6f6..0000000000 --- a/doc_examples/CMakeMake.eb +++ /dev/null @@ -1,30 +0,0 @@ -easyblock = 'CMakeMake' - -name = 'ANTs' -version = '2.1.0rc3' - -homepage = 'http://stnava.github.io/ANTs/' -description = """ANTs extracts information from complex datasets that include imaging. ANTs is useful for managing, - interpreting and visualizing multidimensional data.""" - -toolchain = {'name': 'goolf', 'version': '1.5.14'} -toolchainopts = {'pic': True} - -source_urls = ['https://github.com/stnava/ANTs/archive/'] -sources = ['v%(version)s.tar.gz'] - -builddependencies = [('CMake', '3.0.2')] - -skipsteps = ['install'] -buildopts = ' && mkdir -p %(installdir)s && cp -r * %(installdir)s/' - -parallel = 1 - -separate_build_dir = True - -sanity_check_paths = { - 'files': ['bin/ANTS'], - 'dirs': ['lib'], -} - -moduleclass = 'data' diff --git a/doc_examples/ConfigureMake.eb b/doc_examples/ConfigureMake.eb deleted file mode 100644 index 9a0d4bf65e..0000000000 --- a/doc_examples/ConfigureMake.eb +++ /dev/null @@ -1,20 +0,0 @@ -easyblock = 'ConfigureMake' - -name = 'zsync' -version = '0.6.2' - -homepage = 'http://zsync.moria.org.uk/' -description = """zsync-0.6.2: Optimising file distribution program, a 1-to-many rsync""" - -sources = [SOURCE_TAR_BZ2] -source_urls = ['http://zsync.moria.org.uk/download/'] - - -toolchain = {'name': 'ictce', 'version': '5.3.0'} - -sanity_check_paths = { - 'files': ['bin/zsync'], - 'dirs': [] - } - -moduleclass = 'tools' diff --git a/doc_examples/ConfigureMakePythonPackage.eb b/doc_examples/ConfigureMakePythonPackage.eb deleted file mode 100644 index 0f9fd09a84..0000000000 --- a/doc_examples/ConfigureMakePythonPackage.eb +++ /dev/null @@ -1,33 +0,0 @@ -easyblock = 'ConfigureMakePythonPackage' - -name = 'PyQt' -version = '4.11.3' - -homepage = 'http://www.riverbankcomputing.co.uk/software/pyqt' -description = """PyQt is a set of Python v2 and v3 bindings for Digia's Qt application framework.""" - -toolchain = {'name': 'goolf', 'version': '1.5.14'} - -sources = ['%(name)s-x11-gpl-%(version)s.tar.gz'] -source_urls = ['http://sourceforge.net/projects/pyqt/files/PyQt4/PyQt-%(version)s'] - -python = 'Python' -pyver = '2.7.9' -pythonshortver = '.'.join(pyver.split('.')[:2]) -versionsuffix = '-%s-%s' % (python, pyver) - -dependencies = [ - (python, pyver), - ('SIP', '4.16.4', versionsuffix), - ('Qt', '4.8.6'), -] - -configopts = "configure-ng.py --confirm-license" -configopts += " --destdir=%%(installdir)s/lib/python%s/site-packages " % pythonshortver -configopts += " --no-sip-files" - -options = {'modulename': 'PyQt4'} - -modextrapaths = {'PYTHONPATH': 'lib/python%s/site-packages' % pythonshortver} - -moduleclass = 'vis' From fc8557ef13906d6e856d9ecd34f9f7a69faf815f Mon Sep 17 00:00:00 2001 From: Caroline De Brouwer Date: Fri, 10 Jul 2015 09:13:59 +0200 Subject: [PATCH 18/26] Update on doc for generic easyblocks --- easybuild/tools/docs.py | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/easybuild/tools/docs.py b/easybuild/tools/docs.py index dd94257a94..a46d3b1ed8 100644 --- a/easybuild/tools/docs.py +++ b/easybuild/tools/docs.py @@ -151,11 +151,11 @@ def avail_easyconfig_params(easyblock, output_format): return avail_easyconfig_params_functions[output_format](title, grouped_params) -def gen_easyblocks_overview_rst(path_to_examples, common_params={}, doc_functions=[]): +def gen_easyblocks_overview_rst(package_name, path_to_examples, common_params={}, doc_functions=[]): """ - Compose overview of all generic easyblocks in rst format + Compose overview of all easyblocks in the given package in rst format """ - modules = import_available_modules('easybuild.easyblocks.generic') + modules = import_available_modules(package_name) docs = [] all_blocks = [] @@ -164,7 +164,7 @@ def gen_easyblocks_overview_rst(path_to_examples, common_params={}, doc_function for name,obj in inspect.getmembers(m, inspect.isclass): eb_class = getattr(m, name) # skip imported classes that are not easyblocks - if eb_class.__module__.startswith('easybuild.easyblocks.generic') and eb_class not in all_blocks: + if eb_class.__module__.startswith(package_name) and eb_class not in all_blocks: all_blocks.append(eb_class) for eb_class in all_blocks: @@ -172,7 +172,7 @@ def gen_easyblocks_overview_rst(path_to_examples, common_params={}, doc_function title = 'Overview of generic easyblocks' - heading = ['=' * len(title), title, '=' * len(title), '', '.. contents::', ' :depth: 1', ''] + heading = ['=' * len(title), title, '=' * len(title), '', '.. contents::', ' :depth: 2', ''] return heading + sorted(docs) def gen_easyblock_doc_section_rst(eb_class, path_to_examples, common_params, doc_functions, all_blocks): @@ -182,7 +182,8 @@ def gen_easyblock_doc_section_rst(eb_class, path_to_examples, common_params, doc classname = eb_class.__name__ lines = [ - '.. ' + classname + ':', + '.. _' + classname + ':', + '', '``' + classname + '``', '=' * (len(classname)+4), '', From 7a36365c4cfab08cb3ec8cfe25bde4bb59bbd3a6 Mon Sep 17 00:00:00 2001 From: Caroline De Brouwer Date: Mon, 13 Jul 2015 10:42:58 +0200 Subject: [PATCH 19/26] sorted imports --- easybuild/tools/docs.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/easybuild/tools/docs.py b/easybuild/tools/docs.py index a46d3b1ed8..85f06ae304 100644 --- a/easybuild/tools/docs.py +++ b/easybuild/tools/docs.py @@ -39,9 +39,9 @@ from easybuild.framework.easyconfig.default import DEFAULT_CONFIG, HIDDEN, sorted_categories from easybuild.framework.easyconfig.easyconfig import get_easyblock_class -from easybuild.tools.ordereddict import OrderedDict -from easybuild.tools.utilities import quote_str, import_available_modules from easybuild.tools.filetools import read_file +from easybuild.tools.ordereddict import OrderedDict +from easybuild.tools.utilities import import_available_modules, quote_str FORMAT_RST = 'rst' From 9204337da20074ec5d1a1393f1fe6d949870fc09 Mon Sep 17 00:00:00 2001 From: Caroline De Brouwer Date: Mon, 13 Jul 2015 11:15:51 +0200 Subject: [PATCH 20/26] Fixed remarks --- easybuild/tools/docs.py | 43 +++++++++++++++++++++++++++-------------- test/framework/docs.py | 26 ++++++++++++------------- 2 files changed, 42 insertions(+), 27 deletions(-) diff --git a/easybuild/tools/docs.py b/easybuild/tools/docs.py index 85f06ae304..433f62bea4 100644 --- a/easybuild/tools/docs.py +++ b/easybuild/tools/docs.py @@ -73,7 +73,7 @@ def avail_easyconfig_params_rst(title, grouped_params): values = [ ['``' + name + '``' for name in grouped_params[grpname].keys()], # parameter name [x[0] for x in grouped_params[grpname].values()], # description - [str(quote_str(x[1])) for x in grouped_params[grpname].values()] #default value + [str(quote_str(x[1])) for x in grouped_params[grpname].values()] # default value ] lines.extend(mk_rst_table(titles, values)) @@ -81,6 +81,7 @@ def avail_easyconfig_params_rst(title, grouped_params): return '\n'.join(lines) + def avail_easyconfig_params_txt(title, grouped_params): """ Compose overview of available easyconfig parameters, in plain text format. @@ -106,6 +107,7 @@ def avail_easyconfig_params_txt(title, grouped_params): return '\n'.join(lines) + def avail_easyconfig_params(easyblock, output_format): """ Compose overview of available easyconfig parameters, in specified format. @@ -160,20 +162,30 @@ def gen_easyblocks_overview_rst(package_name, path_to_examples, common_params={} all_blocks = [] # get all blocks - for m in modules: - for name,obj in inspect.getmembers(m, inspect.isclass): - eb_class = getattr(m, name) + for mod in modules: + for name,obj in inspect.getmembers(mod, inspect.isclass): + eb_class = getattr(mod, name) # skip imported classes that are not easyblocks if eb_class.__module__.startswith(package_name) and eb_class not in all_blocks: all_blocks.append(eb_class) - for eb_class in all_blocks: + for eb_class in sorted(all_blocks): docs.append(gen_easyblock_doc_section_rst(eb_class, path_to_examples, common_params, doc_functions, all_blocks)) title = 'Overview of generic easyblocks' - heading = ['=' * len(title), title, '=' * len(title), '', '.. contents::', ' :depth: 2', ''] - return heading + sorted(docs) + heading = [ + '=' * len(title), + title, + '=' * len(title), + '', + '.. contents::', + ' :depth: 2', + '', + ] + + return heading + docs + def gen_easyblock_doc_section_rst(eb_class, path_to_examples, common_params, doc_functions, all_blocks): """ @@ -220,20 +232,23 @@ def gen_easyblock_doc_section_rst(eb_class, path_to_examples, common_params, doc commonly_used = 'Commonly used easyconfig parameters with ``' + classname + '`` easyblock' lines.extend([commonly_used, '-' * len(commonly_used)]) - for opt in common_params[classname]: - param = '* ``' + opt + '`` - ' + DEFAULT_CONFIG[opt][1] - lines.append(param) - lines.append('') + titles = ['easyconfig parameter', 'description'] + values = [ + [common_params[classname]], + [DEFAULT_CONFIG[opt][1] for opt in common_params], + ] + + lines.extend(mk_rst_table(titles, values)) + + lines.append('') # Add docstring for custom steps custom = [] inh = '' + f = None for func in doc_functions: if func in eb_class.__dict__: f = eb_class.__dict__[func] - elif func in eb_class.__bases__[0].__dict__: - f = eb_class.__bases__[0].__dict__[func] - inh = ' (inherited)' if f.__doc__: custom.append('* ``' + func + '`` - ' + f.__doc__.strip() + inh) diff --git a/test/framework/docs.py b/test/framework/docs.py index 36f0d997f0..f05e68f3a1 100644 --- a/test/framework/docs.py +++ b/test/framework/docs.py @@ -34,24 +34,24 @@ class DocsTest(EnhancedTestCase): def test_rst_table(self): """ Test mk_rst_table function """ - entries_1 = [['one', 'two', 'three']] - t1 = 'This title is long' - titles_1 = [t1] + entries = [['one', 'two', 'three']] + t = 'This title is longer than the entries in the column' + titles = [t] # small table - table_1 = '\n'.join(mk_rst_table(titles_1, entries_1)) - check_1 = '\n'.join([ - '=' * len(t1), - t1, - '=' * len(t1), - 'one' + ' ' * (len(t1) - 3), - 'two' + ' ' * (len(t1) -3), - 'three' + ' ' * (len(t1) - 5), - '=' * len(t1), + table = '\n'.join(mk_rst_table(titles, entries)) + check = '\n'.join([ + '=' * len(t), + t, + '=' * len(t), + 'one' + ' ' * (len(t) - 3), + 'two' + ' ' * (len(t) -3), + 'three' + ' ' * (len(t) - 5), + '=' * len(t), '', ]) - self.assertEqual(table_1, check_1) + self.assertEqual(table, check) def suite(): From 8a4ec13b44f5bf3997c560e3a8935b8abd7970ef Mon Sep 17 00:00:00 2001 From: Caroline De Brouwer Date: Mon, 13 Jul 2015 11:38:04 +0200 Subject: [PATCH 21/26] sort easyblocks --- easybuild/tools/docs.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/easybuild/tools/docs.py b/easybuild/tools/docs.py index 433f62bea4..7495e7baa5 100644 --- a/easybuild/tools/docs.py +++ b/easybuild/tools/docs.py @@ -169,7 +169,8 @@ def gen_easyblocks_overview_rst(package_name, path_to_examples, common_params={} if eb_class.__module__.startswith(package_name) and eb_class not in all_blocks: all_blocks.append(eb_class) - for eb_class in sorted(all_blocks): + for eb_class in sorted(all_blocks, key=lambda c: c.__name__): + print eb_class docs.append(gen_easyblock_doc_section_rst(eb_class, path_to_examples, common_params, doc_functions, all_blocks)) title = 'Overview of generic easyblocks' From a48c80beeded792f6425830925fd15e1ed4a6517 Mon Sep 17 00:00:00 2001 From: Caroline De Brouwer Date: Mon, 13 Jul 2015 11:47:24 +0200 Subject: [PATCH 22/26] remove debug print --- easybuild/tools/docs.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/easybuild/tools/docs.py b/easybuild/tools/docs.py index 7495e7baa5..5e45cf1f08 100644 --- a/easybuild/tools/docs.py +++ b/easybuild/tools/docs.py @@ -170,7 +170,6 @@ def gen_easyblocks_overview_rst(package_name, path_to_examples, common_params={} all_blocks.append(eb_class) for eb_class in sorted(all_blocks, key=lambda c: c.__name__): - print eb_class docs.append(gen_easyblock_doc_section_rst(eb_class, path_to_examples, common_params, doc_functions, all_blocks)) title = 'Overview of generic easyblocks' @@ -182,6 +181,8 @@ def gen_easyblocks_overview_rst(package_name, path_to_examples, common_params={} '', '.. contents::', ' :depth: 2', + ' :local', + ' :backlinks: top', '', ] From b48bf8c76fbd13fa9c47657c46c1688e5a59cb07 Mon Sep 17 00:00:00 2001 From: Caroline De Brouwer Date: Mon, 13 Jul 2015 11:49:41 +0200 Subject: [PATCH 23/26] forgot a ':' --- easybuild/tools/docs.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/easybuild/tools/docs.py b/easybuild/tools/docs.py index 5e45cf1f08..4374f6e53b 100644 --- a/easybuild/tools/docs.py +++ b/easybuild/tools/docs.py @@ -181,7 +181,7 @@ def gen_easyblocks_overview_rst(package_name, path_to_examples, common_params={} '', '.. contents::', ' :depth: 2', - ' :local', + ' :local:', ' :backlinks: top', '', ] From 307ae84cebce4fee72627450fc8fd069e0579aaa Mon Sep 17 00:00:00 2001 From: Caroline De Brouwer Date: Tue, 14 Jul 2015 16:48:54 +0200 Subject: [PATCH 24/26] rst documentation for generic easyblocks unit test --- easybuild/tools/docs.py | 8 +++--- test/framework/docs.py | 62 ++++++++++++++++++++++++++++++++++++++++- 2 files changed, 65 insertions(+), 5 deletions(-) diff --git a/easybuild/tools/docs.py b/easybuild/tools/docs.py index 5e45cf1f08..078488bd72 100644 --- a/easybuild/tools/docs.py +++ b/easybuild/tools/docs.py @@ -180,8 +180,8 @@ def gen_easyblocks_overview_rst(package_name, path_to_examples, common_params={} '=' * len(title), '', '.. contents::', - ' :depth: 2', - ' :local', + ' :depth: 1', + ' :local:', ' :backlinks: top', '', ] @@ -236,8 +236,8 @@ def gen_easyblock_doc_section_rst(eb_class, path_to_examples, common_params, doc titles = ['easyconfig parameter', 'description'] values = [ - [common_params[classname]], - [DEFAULT_CONFIG[opt][1] for opt in common_params], + [opt for opt in common_params[classname]], + [DEFAULT_CONFIG[opt][1] for opt in common_params[classname]], ] lines.extend(mk_rst_table(titles, values)) diff --git a/test/framework/docs.py b/test/framework/docs.py index f05e68f3a1..26eb9f07a2 100644 --- a/test/framework/docs.py +++ b/test/framework/docs.py @@ -26,9 +26,15 @@ Unit tests for docs.py. """ +import os +import re +import sys +import inspect + +from easybuild.tools.docs import gen_easyblocks_overview_rst, mk_rst_table +from easybuild.tools.utilities import import_available_modules from test.framework.utilities import EnhancedTestCase, init_config from unittest import TestLoader, main -from easybuild.tools.docs import mk_rst_table class DocsTest(EnhancedTestCase): @@ -53,6 +59,60 @@ def test_rst_table(self): self.assertEqual(table, check) + def test_gen_easyblocks(self): + """ Test gen_easyblocks_overview_rst function """ + module = 'easybuild.easyblocks.generic' + modules = import_available_modules(module) + common_params = { + 'ConfigureMake' : ['configopts', 'buildopts', 'installopts'], + } + doc_functions = ['build_step', 'configure_step', 'test_step'] + + eb_overview = gen_easyblocks_overview_rst(module, 'easyconfigs', common_params, doc_functions) + ebdoc = '\n'.join(eb_overview) + + # extensive check for ConfigureMake easyblock + check_configuremake = '\n'.join([ + ".. _ConfigureMake:", + '', + "``ConfigureMake``", + "=================", + '', + "(derives from EasyBlock)", + '', + "Dummy support for building and installing applications with configure/make/make install.", + '', + "Commonly used easyconfig parameters with ``ConfigureMake`` easyblock", + "--------------------------------------------------------------------", + "==================== ================================================================", + "easyconfig parameter description ", + "==================== ================================================================", + "configopts Extra options passed to configure (default already has --prefix)", + "buildopts Extra options passed to make step (default already has -j X) ", + "installopts Extra options for installation ", + "==================== ================================================================", + ]) + + self.assertTrue(check_configuremake in ebdoc) + + for mod in modules: + for name, obj in inspect.getmembers(mod, inspect.isclass): + eb_class = getattr(mod, name) + # skip imported classes that are not easyblocks + if eb_class.__module__.startswith(module): + self.assertTrue(name in ebdoc) + + patterns = [ + r'..contents::', + r' :depth: 1', + r' :local:', + r' :backlinks: top' + ] + + for pattern in patterns: + regex = re.compile(pattern) + self.assertTrue(re.search(regex, ebdoc), "Pattern %s found in %s" % (regex.pattern, ebdoc)) + def suite(): """ returns all test cases in this module """ From cb4bd0f032675a066263f702c3803e3afcad968e Mon Sep 17 00:00:00 2001 From: Caroline De Brouwer Date: Wed, 15 Jul 2015 16:40:31 +0200 Subject: [PATCH 25/26] table of contents as list --- easybuild/tools/docs.py | 10 ++++++---- test/framework/docs.py | 15 ++++++--------- 2 files changed, 12 insertions(+), 13 deletions(-) diff --git a/easybuild/tools/docs.py b/easybuild/tools/docs.py index 078488bd72..6e28ab18f8 100644 --- a/easybuild/tools/docs.py +++ b/easybuild/tools/docs.py @@ -179,13 +179,15 @@ def gen_easyblocks_overview_rst(package_name, path_to_examples, common_params={} title, '=' * len(title), '', - '.. contents::', - ' :depth: 1', - ' :local:', - ' :backlinks: top', + '*(this page was generated automatically using* ``easybuild.tools.docs.gen_easyblocks_overview_rst()`` *)*', '', ] + contents = [":ref:`" + b.__name__ + "`" for b in sorted(all_blocks, key=lambda b: b.__name__)] + toc = ' - '.join(contents) + heading.append(toc) + heading.append('') + return heading + docs diff --git a/test/framework/docs.py b/test/framework/docs.py index 26eb9f07a2..50c8e1c3bb 100644 --- a/test/framework/docs.py +++ b/test/framework/docs.py @@ -94,6 +94,7 @@ def test_gen_easyblocks(self): ]) self.assertTrue(check_configuremake in ebdoc) + names = [] for mod in modules: for name, obj in inspect.getmembers(mod, inspect.isclass): @@ -101,17 +102,13 @@ def test_gen_easyblocks(self): # skip imported classes that are not easyblocks if eb_class.__module__.startswith(module): self.assertTrue(name in ebdoc) + names.append(name) - patterns = [ - r'..contents::', - r' :depth: 1', - r' :local:', - r' :backlinks: top' - ] + toc = [":ref:`" + n + "`" for n in sorted(names)] + pattern = " - ".join(toc) - for pattern in patterns: - regex = re.compile(pattern) - self.assertTrue(re.search(regex, ebdoc), "Pattern %s found in %s" % (regex.pattern, ebdoc)) + regex = re.compile(pattern) + self.assertTrue(re.search(regex, ebdoc), "Pattern %s found in %s" % (regex.pattern, ebdoc)) def suite(): From 3c394ae9bc9aad447c4e1240b5e03fc4f28f7572 Mon Sep 17 00:00:00 2001 From: Caroline De Brouwer Date: Wed, 15 Jul 2015 16:58:43 +0200 Subject: [PATCH 26/26] remark above title --- easybuild/tools/docs.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/easybuild/tools/docs.py b/easybuild/tools/docs.py index 6e28ab18f8..17a43636b5 100644 --- a/easybuild/tools/docs.py +++ b/easybuild/tools/docs.py @@ -175,12 +175,12 @@ def gen_easyblocks_overview_rst(package_name, path_to_examples, common_params={} title = 'Overview of generic easyblocks' heading = [ + '*(this page was generated automatically using* ``easybuild.tools.docs.gen_easyblocks_overview_rst()`` *)*', + '', '=' * len(title), title, '=' * len(title), '', - '*(this page was generated automatically using* ``easybuild.tools.docs.gen_easyblocks_overview_rst()`` *)*', - '', ] contents = [":ref:`" + b.__name__ + "`" for b in sorted(all_blocks, key=lambda b: b.__name__)]