Merge branch 'new-projects' into 'master'

Implements new project creation closes #3 and #6

Closes #3 and #6

See merge request !4

MANIFEST.in

 include LICENSE README.rst buildout.cfg version.txt
-recursive-include doc conf.py *.rst *.sh
+recursive-include doc conf.py *.rst *.sh *.png *.ico
 recursive-include bob/devtools/data *.md *.yaml *.pem matplotlibrc
+recursive-include bob/devtools/templates conf.py *.rst *.png *.ico LICENSE COPYING .gitlab-ci.yml .gitignore *.cfg *.txt *.py

bob/devtools/scripts/new.py

+#!/usr/bin/env python
+
+import os
+import shutil
+import logging
+import datetime
+logger = logging.getLogger(__name__)
+
+import click
+import jinja2
+import pkg_resources
+
+from . import bdt
+from ..log import verbosity_option
+
+
+def copy_file(template, output_dir):
+  '''Copies a file from the template directory to the output directory
+
+  Args:
+
+    template: The path to the template, from the internal templates directory
+    output_dir: Where to save the output
+  '''
+
+  template_file = pkg_resources.resource_filename(__name__, os.path.join('..',
+    'templates', template))
+  output_file = os.path.join(output_dir, template)
+
+  basedir = os.path.dirname(output_file)
+  if not os.path.exists(basedir):
+    logger.info('mkdir %s', basedir)
+    os.makedirs(basedir)
+
+  logger.info('cp -a %s %s', template_file, output_file)
+  shutil.copy2(template_file, output_file)
+
+
+def render_template(jenv, template, context, output_dir):
+  '''Renders a template to the output directory using specific context
+
+  Args:
+
+    jenv: The Jinja2 environment to use for rendering the template
+    template: The path to the template, from the internal templates directory
+    context: A dictionary with the context to render the template with
+    output_dir: Where to save the output
+  '''
+
+  output_file = os.path.join(output_dir, template)
+
+  basedir = os.path.dirname(output_file)
+  if not os.path.exists(basedir):
+    logger.info('mkdir %s', basedir)
+    os.makedirs(basedir)
+
+  with open(output_file, 'wt') as f:
+    logger.info('rendering %s', output_file)
+    T = jenv.get_template(template)
+    f.write(T.render(**context))
+
+
+@click.command(epilog='''
+Examples:
+
+  1. Generates a new project for Bob:
+
+     $ bdt new -vv bob/bob.newpackage "John Doe" "joe@example.com"
+''')
+@click.argument('package')
+@click.argument('author')
+@click.argument('email')
+@click.option('-t', '--title', show_default=True,
+    default='New package', help='This entry defines the package title. ' \
+        'The package title should be a few words only.  It will appear ' \
+        'at the description of your package and as the title of your ' \
+        'documentation')
+@click.option('-l', '--license', type=click.Choice(['bsd', 'gplv3']),
+    default='gplv3', show_default=True,
+    help='Changes the default licensing scheme to use for your package')
+@click.option('-o', '--output-dir', help='Directory where to dump the new ' \
+          'project - must not exist')
+@verbosity_option()
+@bdt.raise_on_error
+def new(package, author, email, title, license, output_dir):
+    """Creates a folder structure for a new Bob/BEAT package
+    """
+
+    if '/' not in package:
+        raise RuntimeError('PACKAGE should be specified as "group/name"')
+
+    group, name = package.split('/')
+
+    # creates the rst title, which looks like this:
+    # =======
+    #  Title
+    # =======
+    rst_title = ('=' * (2+len(title))) + '\n ' + title + '\n' + \
+        ('=' * (2+len(title)))
+
+    # the jinja context defines the substitutions to be performed
+    today = datetime.datetime.today()
+    context = dict(
+        package = package,
+        group = group,
+        name = name,
+        author = author,
+        email = email,
+        title = title,
+        rst_title = rst_title,
+        license = license,
+        year = today.strftime('%Y'),
+        date = today.strftime('%c'),
+        )
+
+    # copy the whole template structure and de-templatize the needed files
+    if output_dir is None:
+      output_dir = os.path.join(os.path.realpath(os.curdir), name)
+    logger.info('Creating structure for %s at directory %s', package,
+        output_dir)
+
+    if os.path.exists(output_dir):
+      raise IOError('The package directory %s already exists - cannot '
+          'overwrite!' % output_dir)
+
+    logger.info('mkdir %s', output_dir)
+    os.makedirs(output_dir)
+
+    # base jinja2 engine
+    env = jinja2.Environment(
+        loader=jinja2.PackageLoader('bob.devtools', 'templates'),
+        autoescape=jinja2.select_autoescape(['html', 'xml'])
+        )
+
+    # other standard files
+    simple = [
+        'requirements.txt',
+        'buildout.cfg',
+        'MANIFEST.in',
+        'setup.py',
+        '.gitignore',
+        'doc/index.rst',
+        'doc/conf.py',
+        'doc/links.rst',
+        '.gitlab-ci.yml',
+        'README.rst',
+        'version.txt',
+        ]
+    for k in simple:
+      render_template(env, k, context, output_dir)
+
+    # handles the license file
+    if license == 'gplv3':
+      render_template(env, 'COPYING', context, output_dir)
+    else:
+      render_template(env, 'LICENSE', context, output_dir)
+
+    # creates the base python module structure
+    template_dir = pkg_resources.resource_filename(__name__, os.path.join('..',
+      'templates'))
+    logger.info('Creating base %s python module', group)
+    shutil.copytree(os.path.join(template_dir, 'pkg'),
+        os.path.join(output_dir, group))
+
+    # copies specific images to the right spot
+    copy_file(os.path.join('doc', 'img', '%s-favicon.ico' % group), output_dir)
+    copy_file(os.path.join('doc', 'img', '%s-128x128.png' % group), output_dir)
+    copy_file(os.path.join('doc', 'img', '%s-logo.png' % group), output_dir)
+
+    # finally, render the conda recipe template-template!
+    # this one is special since it is already a jinja2 template
+    conda_env = jinja2.Environment(
+        loader=jinja2.PackageLoader('bob.devtools', 'templates'),
+        autoescape=jinja2.select_autoescape(['html', 'xml']),
+        block_start_string='(%', block_end_string='%)',
+        variable_start_string='((', variable_end_string='))',
+        comment_start_string='(#', comment_end_string='#)',
+        )
+    render_template(conda_env, os.path.join('conda', 'meta.yaml'), context,
+        output_dir)

bob/devtools/templates/.gitignore

+*~
+*.swp
+*.pyc
+bin
+eggs
+parts
+.installed.cfg
+.mr.developer.cfg
+*.egg-info
+src
+develop-eggs
+sphinx
+dist
+.nfs*
+.gdb_history
+build
+.coverage
+record.txt
+miniconda.sh
+miniconda/

bob/devtools/templates/.gitlab-ci.yml

+include: 'https://gitlab.idiap.ch/bob/bob.devtools/raw/master/bob/devtools/data/gitlab-ci/single-package.yaml'

bob/devtools/templates/LICENSE

+Copyright (c) {{ year }} Idiap Research Institute, http://www.idiap.ch/
+Written by {{ author }} <{{ email }}>
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+may be used to endorse or promote products derived from this software without
+specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

bob/devtools/templates/MANIFEST.in

+include README.rst buildout.cfg {% if license.startswith('gpl') %}COPYING {% endif %}version.txt requirements.txt
+recursive-include doc *.rst *.png *.ico *.txt

bob/devtools/templates/README.rst

+.. -*- coding: utf-8 -*-
+
+.. image:: https://img.shields.io/badge/docs-stable-yellow.svg
+   :target: https://www.idiap.ch/software/bob/docs/{{ package }}/stable/index.html
+.. image:: https://img.shields.io/badge/docs-latest-orange.svg
+   :target: https://www.idiap.ch/software/bob/docs/{{ package }}/master/index.html
+.. image:: https://gitlab.idiap.ch/{{ package }}/badges/master/build.svg
+   :target: https://gitlab.idiap.ch/{{ package }}/commits/master
+.. image:: https://gitlab.idiap.ch/{{ package }}/badges/master/coverage.svg
+   :target: https://gitlab.idiap.ch/{{ package }}/commits/master
+.. image:: https://img.shields.io/badge/gitlab-project-0000c0.svg
+   :target: https://gitlab.idiap.ch/{{ package }}
+.. image:: https://img.shields.io/pypi/v/{{ name }}.svg
+   :target: https://pypi.python.org/pypi/{{ name }}
+
+
+{{ rst_title }}
+
+This package is part of {% if group == "bob" %}the signal-processing and machine learning toolbox Bob_{% else %}BEAT_, an open-source evaluation platform for data science algorithms and workflows{% endif %}.
+
+.. todo::
+
+   **Complete the sentence above to include one phrase about your
+   package!  Once this is done, delete this to-do!**
+
+
+Installation
+------------
+
+Complete {{ group }}'s `installation`_ instructions. Then, to install this
+package, run::
+
+  $ conda install {{ name }}
+
+
+Contact
+-------
+
+For questions or reporting issues to this software package, contact our
+development `mailing list`_.
+
+
+.. Place your references here:
+.. _{{ group }}: https://www.idiap.ch/software/{{ group }}
+.. _installation: https://www.idiap.ch/software/{{ group }}/install
+.. _mailing list: https://www.idiap.ch/software/{{ group }}/discuss

bob/devtools/templates/buildout.cfg

+; -*- coding: utf-8 -*-
+; {{ date }}
+
+[buildout]
+parts = scripts
+develop = .
+eggs = {{ name }}
+extensions = bob.buildout
+newest = false
+verbose = true
+
+[scripts]
+recipe = bob.buildout:scripts
+dependent-scripts = true

bob/devtools/templates/conda/meta.yaml

+{% set name = '(( name ))' %}
+{% set project_dir = environ.get('RECIPE_DIR') + '/..' %}
+
+package:
+  name: {{ name }}
+  version: {{ environ.get('BOB_PACKAGE_VERSION', '0.0.1') }}
+
+build:
+  number: {{ environ.get('BOB_BUILD_NUMBER', 0) }}
+  run_exports:
+    - {{ pin_subpackage(name) }}
+  script:
+    - cd {{ project_dir }}
+    {% if environ.get('BUILD_EGG') %}
+    - python setup.py sdist --formats=zip
+    {% endif %}
+    - python setup.py install --single-version-externally-managed --record record.txt
+
+requirements:
+  # place your build dependencies before the 'host' section
+  host:
+    - python {{ python }}
+    - setuptools {{ setuptools }}
+    # place your other host dependencies here
+  run:
+    - python
+    - setuptools
+    # place other runtime dependencies here (same as requirements.txt)
+
+test:
+  imports:
+    - {{ name }}
+  commands:
+    # test commands ("script" entry-points) from your package here
+    - nosetests --with-coverage --cover-package={{ name }} -sv {{ name }}
+    - sphinx-build -aEW {{ project_dir }}/doc {{ project_dir }}/sphinx
+    - sphinx-build -aEb doctest {{ project_dir }}/doc sphinx
+    - conda inspect linkages -p $PREFIX {{ name }}  # [not win]
+    - conda inspect objects -p $PREFIX {{ name }}  # [osx]
+  requires:
+    - bob-devel {{ bob_devel }}.*
+    - nose
+    - coverage
+    - sphinx
+    - sphinx_rtd_theme
+    # extend this list with further test-time-only dependencies
+
+about:
+  home: https://www.idiap.ch/software/bob/
+  license: (% if license == 'gplv3' %)GNU General Public License v3 (GPLv3)(% else %)BSD 3-Clause(% endif %)
+  license_family: (% if license == 'gplv3' %)GPL(% else %)BSD(% endif %)
+  summary: (( title ))

bob/devtools/templates/doc/conf.py

+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import os
+import pkg_resources
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+needs_sphinx = '1.3'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = [
+    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
+    'sphinx.ext.ifconfig',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.doctest',
+    'sphinx.ext.graphviz',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.mathjax',
+    #'matplotlib.sphinxext.plot_directive'
+]
+
+# Be picky about warnings
+nitpicky = False
+
+# Ignores stuff we can't easily resolve on other project's sphinx manuals
+nitpick_ignore = []
+
+# Allows the user to override warnings from a separate file
+if os.path.exists('nitpick-exceptions.txt'):
+    for line in open('nitpick-exceptions.txt'):
+        if line.strip() == "" or line.startswith("#"):
+            continue
+        dtype, target = line.split(None, 1)
+        target = target.strip()
+        nitpick_ignore.append((dtype, target))
+
+# Always includes todos
+todo_include_todos = True
+
+# Generates auto-summary automatically
+autosummary_generate = True
+
+# Create numbers on figures with captions
+numfig = True
+
+# If we are on OSX, the 'dvipng' path maybe different
+dvipng_osx = '/Library/TeX/texbin/dvipng'
+if os.path.exists(dvipng_osx):
+    pngmath_dvipng = dvipng_osx
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'{{ name }}'
+import time
+copyright = u'%s, Idiap Research Institute' % time.strftime('%Y')
+
+# Grab the setup entry
+distribution = pkg_resources.require(project)[0]
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = distribution.version
+# The full version, including alpha/beta/rc tags.
+release = distribution.version
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['links.rst']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# Some variables which are useful for generated material
+project_variable = project.replace('.', '_')
+short_description = u'{{ title }}'
+owner = [u'Idiap Research Institute']
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+import sphinx_rtd_theme
+html_theme = 'sphinx_rtd_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = project_variable
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+html_logo = 'img/{{ group }}-logo.png'
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+html_favicon = 'img/{{ group }}-favicon.ico'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+#html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = project_variable + u'_doc'
+
+# -- Post configuration --------------------------------------------------------
+
+# Included after all input documents
+rst_epilog = """
+.. |project| replace:: Bob
+.. |version| replace:: %s
+.. |current-year| date:: %%Y
+""" % (version, )
+
+# Default processing flags for sphinx
+autoclass_content = 'class'
+autodoc_member_order = 'bysource'
+autodoc_default_flags = [
+    'members',
+    'undoc-members',
+    'show-inheritance',
+]
+
+# For inter-documentation mapping:
+from bob.extension.utils import link_documentation, load_requirements
+sphinx_requirements = "extra-intersphinx.txt"
+if os.path.exists(sphinx_requirements):
+    intersphinx_mapping = link_documentation(
+        additional_packages=['python', 'numpy'] +
+        load_requirements(sphinx_requirements))
+else:
+    intersphinx_mapping = link_documentation()
+
+# We want to remove all private (i.e. _. or __.__) members
+# that are not in the list of accepted functions
+accepted_private_functions = ['__array__']
+
+
+def member_function_test(app, what, name, obj, skip, options):
+    # test if we have a private function
+    if len(name) > 1 and name[0] == '_':
+        # test if this private function should be allowed
+        if name not in accepted_private_functions:
+            # omit privat functions that are not in the list of accepted private functions
+            return skip
+        else:
+            # test if the method is documented
+            if not hasattr(obj, '__doc__') or not obj.__doc__:
+                return skip
+    return False
+
+
+def setup(app):
+    app.connect('autodoc-skip-member', member_function_test)

bob/devtools/templates/doc/index.rst

+.. -*- coding: utf-8 -*-
+
+.. _{{ package }}:
+
+{{ rst_title }}
+
+.. todo ::
+   Write here a small (1 paragraph) introduction explaining this project. See
+   other projects for examples.
+
+
+
+Users Guide
+===========
+
+.. toctree::
+   :maxdepth: 2
+
+   api
+
+.. todolist::
+
+.. include:: links.rst

bob/devtools/templates/doc/links.rst

+.. -*- coding: utf-8 -*-
+
+.. This file contains all links we use for documentation in a centralized place
+
+.. _idiap: http://www.idiap.ch
+.. _bob: http://www.idiap.ch/software/bob
+.. _installation: https://www.idiap.ch/software/bob/install
+.. _mailing list: https://www.idiap.ch/software/bob/discuss