Merge pull request #91 from automl/development

Prepare release 0.2

README.md

@@ -5,6 +5,8 @@ Copyright (C) 2016  [ML4AAD Group](http://www.ml4aad.org/)
 __Attention__: This package is under heavy development and subject to change. 
 A stable release of SMAC (v2) in Java can be found [here](http://www.cs.ubc.ca/labs/beta/Projects/SMAC/).
 
+The documentation can be found [here](https://automl.github.io/SMAC3/).
+
 Status for master branch:
 
 [![Build Status](https://travis-ci.org/automl/SMAC3.svg?branch=master)](https://travis-ci.org/automl/SMAC3)
@@ -33,7 +35,7 @@ we refer to
     In: Proceedings of the conference on Learning and Intelligent OptimizatioN (LION 5)
 
 
-SMAC v3 is mainly written in Python 3.4. We expect that it should be also compatible with Python 2.7. 
+SMAC v3 is written in python3 and continuously tested with python3.4 and python3.5. 
 Its [Random Forest](https://bitbucket.org/aadfreiburg/random_forest_run) is written in C++.
 
 #Installation:

changelog.md

@@ -1,3 +1,22 @@
+# 0.2
+
+* ADD 55: Separate modules for the initial design and a more flexible 
+  constructor for the SMAC class
+* ADD 41: Add ROAR (random online adaptive racing) class
+* ADD 82: Add fmin_smac, a scipy.optimize.fmin_l_bfgs_b-like interface to the
+  SMAC algorithm
+* NEW documentation at https://automl.github.io/SMAC3/stable and 
+  https://automl.github.io/SMAC3/dev
+* FIX 62: intensification previously used a random seed from np.random 
+  instead of from SMAC's own random number generator
+* FIX 42: class RunHistory can now be pickled
+* FIX 48: stats and runhistory objects are now injected into the target 
+  algorithm execution classes
+* FIX 72: it is now mandatory to either specify a configuration space or to 
+  pass the path to a PCS file
+* FIX 49: allow passing a callable directly to SMAC. SMAC will wrap the 
+  callable with the appropriate target algorithm runner
+
 # 0.1.3
 
 * FIX 63 using memory limit for function target algorithms (broken since 0.1.1)

ci_scripts/push_doc.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# This script is meant to be called in the "deploy" step defined in 
+# circle.yml. See https://circleci.com/docs/ for more details.
+# The behavior of the script is controlled by environment variable defined
+# in the circle.yml in the top level folder of the project.
+
+if [ ! -z "$1" ]
+    then DOC_FOLDER=$1
+fi
+
+MSG="Pushing the docs for revision for branch: $CIRCLE_BRANCH, commit $CIRCLE_SHA1, folder: $DOC_FOLDER"
+
+cd $HOME
+
+# Clone the docs repo if it isnt already there
+if [ ! -d $DOC_REPO ];
+    then git clone "[email protected]:$USERNAME/"$DOC_REPO".git";
+fi
+
+# Copy the build docs to a temporary folder
+rm -rf tmp
+mkdir tmp
+cp -R $HOME/$DOC_REPO/doc/build/html/* ./tmp/
+
+cd $DOC_REPO
+git branch gh-pages
+git checkout -f gh-pages
+git reset --hard origin/gh-pages
+git clean -dfx
+git rm -rf $HOME/$DOC_REPO/$DOC_FOLDER && rm -rf $HOME/$DOC_REPO/$DOC_FOLDER
+
+# Copy the new build docs
+mkdir $DOC_FOLDER
+cp -R $HOME/tmp/* ./$DOC_FOLDER/
+
+git config --global user.email $EMAIL
+git config --global user.name $USERNAME
+git add -f ./$DOC_FOLDER/
+git commit -m "$MSG"
+git push -f origin gh-pages
+
+echo $MSG

circle.yml

@@ -0,0 +1,64 @@
+machine:
+  environment:
+    # The github organization or username of the repository which hosts the
+    # project and documentation.
+    USERNAME: "automl"
+
+    # The repository where the documentation will be hosted
+    DOC_REPO: "SMAC3"
+
+    # The base URL for the Github page where the documentation will be hosted
+    DOC_URL: ""
+
+    # The email is to be used for commits in the Github Page
+    EMAIL: "[email protected]"
+
+dependencies:
+
+  # Various dependencies
+  pre:
+    # from scikit-learn contrib
+    - sudo -E apt-get -yq remove texlive-binaries --purge
+    - sudo apt-get update
+    - sudo apt-get install libatlas-dev libatlas3gf-base
+    - sudo apt-get install build-essential python-dev python-setuptools
+    # install numpy first as it is a compile time dependency for other packages
+    - pip install --upgrade numpy
+    # install documentation building dependencies
+    - pip install --upgrade matplotlib setuptools nose coverage sphinx pillow sphinx-gallery sphinx_bootstrap_theme cython numpydoc
+    # Installing required packages for `make -C doc check command` to work.
+    - sudo -E apt-get -yq update
+    - sudo -E apt-get -yq --no-install-suggests --no-install-recommends --force-yes install dvipng texlive-latex-base texlive-latex-extra
+    # Installing packages to build the random forest
+    # finally install the requirements of the package to allow autodoc
+    - pip install -r requirements.txt
+
+  # The --user is needed to let sphinx see the source and the binaries
+  # The pipefail is requested to propagate exit code
+  override:
+    - python setup.py clean
+    - python setup.py develop
+    - set -o pipefail && cd doc && make html 2>&1 | tee ~/log.txt
+test:
+  # Grep error on the documentation
+  override:
+    - cat ~/log.txt && if grep -q "Traceback (most recent call last):" ~/log.txt; then false; else true; fi
+deployment:
+  master:
+    branch: master
+    commands:
+      - bash ci_scripts/push_doc.sh 'stable'
+  development:
+    branch: development
+    commands:
+      - bash ci_scripts/push_doc.sh 'dev'
+general:
+  # Open the doc to the API
+  artifacts:
+    - "doc/_build/html"
+    - "~/log.txt"
+  # Restric the build to the branch master only
+  branches:
+    only:
+       - development
+       - master

Makefile → doc/Makefile

@@ -15,9 +15,9 @@ endif
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
 

doc/_templates/layout.html

@@ -0,0 +1,23 @@
+{% extends "!layout.html" %}
+
+{# Custom CSS overrides #}
+{# set bootswatch_css_custom = ['_static/my-styles.css'] #}
+
+{# Add github banner (from: https://github.com/blog/273-github-ribbons). #}
+{% block header %}
+  {{ super() }}
+  <a href="https://github.com/automl/SMAC3"
+     class="visible-desktop hidden-xs"><img
+    id="gh-banner"
+    style="position: absolute; top: 50px; right: 0; border: 0;"
+    src="https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png"
+    alt="Fork me on GitHub"></a>
+  <script>
+    // Adjust banner height.
+    $(function () {
+      var navHeight = $(".navbar .container").css("height");
+      $("#gh-banner").css("top", navHeight);
+    });
+  </script>
+{% endblock %}
+

source/conf.py → doc/conf.py

@@ -12,9 +12,15 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
+import datetime
 import sys
 import os
 import shlex
+import sphinx_bootstrap_theme
+
+sys.path.insert(0, '..')
+import smac
+
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -52,18 +58,18 @@
 master_doc = 'index'
 
 # General information about the project.
-project = u'SMAC3'
-copyright = u'2015, Marius Lindauer, Stefan Falkner, Katharina Eggensperger, Aaron Klein, Frank Hutter'
-author = u'Marius Lindauer, Stefan Falkner, Katharina Eggensperger, Aaron Klein, Frank Hutter'
+project = u'SMAC'
+copyright = '2015-%s, %s' % (datetime.datetime.now().year, smac.AUTHORS)
+author = smac.AUTHORS
 
 # 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 = '0.0.1dev'
+version = smac.VERSION
 # The full version, including alpha/beta/rc tags.
-release = '0.0.1dev'
+release = smac.VERSION
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -80,7 +86,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = []
+exclude_patterns = ['_static']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -114,15 +120,75 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'alabaster'
+html_theme = 'bootstrap'
 
 # 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 = {}
+html_theme_options = {
+    # Navigation bar title. (Default: ``project`` value)
+    'navbar_title': "SMAC3",
+
+    # Tab name for entire site. (Default: "Site")
+    # 'navbar_site_name': "Site",
+
+    # A list of tuples containting pages to link to.  The value should
+    # be in the form [(name, page), ..]
+    'navbar_links': [
+        ('Start', 'index'),
+        ('Installation', 'installation'),
+        ('Manual', 'manual'),
+        ('Contact', 'contact'),
+	('License', 'license'),
+    ],
+
+    # Render the next and previous page links in navbar. (Default: true)
+    'navbar_sidebarrel': False,
+
+    # Render the current pages TOC in the navbar. (Default: true)
+    'navbar_pagenav': False,
+
+    # Tab name for the current pages TOC. (Default: "Page")
+    'navbar_pagenav_name': "On this page",
+
+    # Global TOC depth for "site" navbar tab. (Default: 1)
+    # Switching to -1 shows all levels.
+    'globaltoc_depth': 1,
+
+    # Include hidden TOCs in Site navbar?
+    #
+    # Note: If this is "false", you cannot have mixed ``:hidden:`` and
+    # non-hidden ``toctree`` directives in the same page, or else the build
+    # will break.
+    #
+    # Values: "true" (default) or "false"
+    'globaltoc_includehidden': "false",
+
+    # HTML navbar class (Default: "navbar") to attach to <div> element.
+    # For black navbar, do "navbar navbar-inverse"
+    'navbar_class': "navbar",
+
+    # Fix navigation bar to top of page?
+    # Values: "true" (default) or "false"
+    'navbar_fixed_top': "true",
+
+    # Location of link to source.
+    # Options are "nav" (default), "footer" or anything else to exclude.
+    'source_link_position': "footer",
+
+    # Bootswatch (http://bootswatch.com/) theme.
+    #
+    # Options are nothing with "" (default) or the name of a valid theme
+    # such as "amelia" or "cosmo".
+    'bootswatch_theme': "cosmo",
+
+    # Choose Bootstrap version.
+    # Values: "3" (default) or "2" (in quotes)
+    'bootstrap_version': "3",
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
+html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -159,7 +225,7 @@
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+html_sidebars = {'**': ['localtoc.html']}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
@@ -228,8 +294,7 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-  (master_doc, 'SMAC3.tex', u'SMAC3 Documentation',
-   u'Marius Lindauer, Stefan Falkner, Katharina Eggensperger, Aaron Klein, Frank Hutter', 'manual'),
+  (master_doc, 'SMAC3.tex', u'SMAC3 Documentation', smac.AUTHORS, 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of

doc/contact.rst

@@ -0,0 +1,7 @@
+Contact
+=======
+
+SMAC v3 is developed by the `ML4AAD Group of the University of Freiburg <http://www.ml4aad.org/>`_.
+
+If you found a bug, please report to https://github.com/automl/SMAC3
+