Generate docs for generic easyblocks (REVIEW)

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'

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'

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'

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'

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'

easybuild/tools/docs.py

@@ -34,25 +34,27 @@
 @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.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.
     """
-    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,
@@ -65,29 +67,14 @@ def det_col_width(entries, title):
         lines.append("%s parameters" % grpname)
         lines.extend(['-' * len(lines[-1]), ''])
 
-        name_title = "**Parameter name**"
-        descr_title = "**Description**"
-        dflt_title = "**Default value**"
-
-        # 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='-'))
+        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()]
+        ]
 
-        # 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)
@@ -160,3 +147,115 @@ 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():
+    """
+    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 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, ''])
+
+    # 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 + '``'