Release preparations (#118)

Added Python tutorial.

.gitexternals

@@ -1,3 +1,3 @@
 # -*- mode: cmake -*-
-# Pydoxine https://github.com/BlueBrain/Pydoxine 3b0783f
-# CMake/common https://github.com/Eyescale/CMake.git b53bf26
+# Pydoxine https://github.com/BlueBrain/Pydoxine 0b62442
+# CMake/common https://github.com/Eyescale/CMake.git 3d5d284

.gitsubprojects

@@ -1,6 +1,6 @@
 # -*- mode: cmake -*-
-git_subproject(Servus https://github.com/HBPVIS/Servus.git 001588d)
-git_subproject(Lunchbox https://github.com/Eyescale/Lunchbox.git 5a37f93)
-git_subproject(Keyv https://github.com/BlueBrain/Keyv.git 7ef03d0)
-git_subproject(vmmlib https://github.com/Eyescale/vmmlib.git caa86d8)
-git_subproject(MVDTool https://github.com/BlueBrain/MVDTool.git fa7523e)
+git_subproject(Servus https://github.com/HBPVIS/Servus.git 2da95ea)
+git_subproject(Lunchbox https://github.com/Eyescale/Lunchbox.git 0ba938f)
+git_subproject(Keyv https://github.com/BlueBrain/Keyv.git a476524)
+git_subproject(vmmlib https://github.com/Eyescale/vmmlib.git 6b7d203)
+git_subproject(MVDTool https://github.com/BlueBrain/MVDTool.git 4e2f0f4)

.travis.yml

@@ -24,6 +24,7 @@ before_install:
   - brew outdated cmake || brew upgrade cmake
   - brew install cppcheck doxygen ninja
   - brew install homebrew/science/hdf5
+  - brew install boost-python
 script:
   - mkdir $BUILD_TYPE
   - cd $BUILD_TYPE

CMake/GitExternal.cmake

@@ -8,7 +8,7 @@
 #    update target to bump the tag to the master revision by
 #    recreating .gitexternals.
 #  * Provides function
-#      git_external(<directory> <giturl> <gittag> [VERBOSE,SHALLOW]
+#      git_external(<directory> <giturl> <gittag> [VERBOSE]
 #        [RESET <files>])
 #    which will check out directory in CMAKE_SOURCE_DIR (if relative)
 #    or in the given absolute path using the given repository and tag
@@ -18,11 +18,6 @@
 #  VERBOSE, when present, this option tells the function to output
 #    information about what operations are being performed by git on
 #    the repo.
-#  SHALLOW, when present, causes a shallow clone of depth 1 to be made
-#    of the specified repo. This may save considerable memory/bandwidth
-#    when only a specific branch of a repo is required and the full history
-#    is not required. Note that the SHALLOW option will only work for a branch
-#    or tag and cannot be used for an arbitrary SHA.
 #  OPTIONAL, when present, this option makes this operation optional.
 #    The function will output a warning and return if the repo could not be
 #    cloned.
@@ -69,15 +64,8 @@ macro(GIT_EXTERNAL_MESSAGE msg)
   endif()
 endmacro()
 
-# utility function for printing a list with custom separator
-function(JOIN VALUES GLUE OUTPUT)
-  string (REGEX REPLACE "([^\\]|^);" "\\1${GLUE}" _TMP_STR "${VALUES}")
-  string (REGEX REPLACE "[\\](.)" "\\1" _TMP_STR "${_TMP_STR}") #fixes escaping
-  set (${OUTPUT} "${_TMP_STR}" PARENT_SCOPE)
-endfunction()
-
 function(GIT_EXTERNAL DIR REPO tag)
-  cmake_parse_arguments(GIT_EXTERNAL_LOCAL "VERBOSE;SHALLOW;OPTIONAL" "" "RESET" ${ARGN})
+  cmake_parse_arguments(GIT_EXTERNAL_LOCAL "VERBOSE;OPTIONAL" "" "RESET" ${ARGN})
   set(TAG ${tag})
   if(GIT_EXTERNAL_TAG AND "${tag}" MATCHES "^[0-9a-f]+$")
     set(TAG ${GIT_EXTERNAL_TAG})
@@ -105,16 +93,9 @@ function(GIT_EXTERNAL DIR REPO tag)
 
   if(NOT EXISTS "${DIR}")
     # clone
-    set(_clone_options --recursive)
-    if(GIT_EXTERNAL_LOCAL_SHALLOW)
-      list(APPEND _clone_options --depth 1 --branch ${TAG})
-    else()
-      set(_msg_tag "[${TAG}]")
-    endif()
-    JOIN("${_clone_options}" " " _msg_text)
-    message(STATUS "git clone ${_msg_text} ${REPO} ${DIR} ${_msg_tag}")
+    message(STATUS "git clone --recursive ${REPO} ${DIR} [${TAG}]")
     execute_process(
-      COMMAND "${GIT_EXECUTABLE}" clone ${_clone_options} ${REPO} ${DIR}
+      COMMAND "${GIT_EXECUTABLE}" clone --recursive ${REPO} ${DIR}
       RESULT_VARIABLE nok ERROR_VARIABLE error
       WORKING_DIRECTORY "${GIT_EXTERNAL_DIR}")
     if(nok)
@@ -127,21 +108,8 @@ function(GIT_EXTERNAL DIR REPO tag)
     endif()
 
     # checkout requested tag
-    if(NOT GIT_EXTERNAL_LOCAL_SHALLOW)
-      execute_process(
-        COMMAND "${GIT_EXECUTABLE}" checkout -q "${TAG}"
-        RESULT_VARIABLE nok ERROR_VARIABLE error
-        WORKING_DIRECTORY "${DIR}")
-      if(nok)
-        message(FATAL_ERROR "git checkout ${TAG} in ${DIR} failed: ${error}\n")
-      endif()
-    endif()
-
-    # checkout requested tag
-    execute_process(
-      COMMAND "${GIT_EXECUTABLE}" checkout -q "${TAG}"
-      RESULT_VARIABLE nok ERROR_VARIABLE error
-      WORKING_DIRECTORY "${DIR}")
+    execute_process(COMMAND "${GIT_EXECUTABLE}" checkout -q "${TAG}"
+      RESULT_VARIABLE nok ERROR_VARIABLE error WORKING_DIRECTORY "${DIR}")
     if(nok)
       message(FATAL_ERROR "git checkout ${TAG} in ${DIR} failed: ${error}\n")
     endif()
@@ -281,13 +249,10 @@ if(EXISTS ${GIT_EXTERNALS} AND NOT GIT_EXTERNAL_SCRIPT_MODE)
           if(NOT TARGET update)
             add_custom_target(update)
           endif()
-          if(NOT TARGET update-gitexternal)
-            add_custom_target(update-gitexternal)
-            add_custom_target(flatten-gitexternal)
-            add_dependencies(update update-gitexternal)
-          endif()
-          if(NOT TARGET ${PROJECT_NAME}-flatten-gitexternal)
+          if(NOT TARGET ${PROJECT_NAME}-update-gitexternal)
+            add_custom_target(${PROJECT_NAME}-update-gitexternal)
             add_custom_target(${PROJECT_NAME}-flatten-gitexternal)
+            add_dependencies(update ${PROJECT_NAME}-update-gitexternal)
           endif()
 
           # Create a unique, flat name
@@ -328,7 +293,7 @@ endif()")
             COMMENT "Update ${REPO} in ${GIT_EXTERNALS_BASE}"
             DEPENDS ${GIT_EXTERNAL_TARGET}
             WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}")
-          add_dependencies(update-gitexternal
+          add_dependencies(${PROJECT_NAME}-update-gitexternal
             update-gitexternal-${GIT_EXTERNAL_NAME})
 
           # Flattens a git external repository into its parent repo:
@@ -346,12 +311,10 @@ endif()")
             COMMENT "Flatten ${REPO} into ${DIR}"
             DEPENDS ${PROJECT_NAME}-make-branch
             WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/${DIR}")
-          add_dependencies(flatten-gitexternal
-            flatten-gitexternal-${GIT_EXTERNAL_NAME})
           add_dependencies(${PROJECT_NAME}-flatten-gitexternal
             flatten-gitexternal-${GIT_EXTERNAL_NAME})
 
-          foreach(_target flatten-gitexternal-${GIT_EXTERNAL_NAME} ${PROJECT_NAME}-flatten-gitexternal flatten-gitexternal update-gitexternal-${GIT_EXTERNAL_NAME} ${GIT_EXTERNAL_TARGET} update-gitexternal update)
+          foreach(_target flatten-gitexternal-${GIT_EXTERNAL_NAME} ${PROJECT_NAME}-flatten-gitexternal update-gitexternal-${GIT_EXTERNAL_NAME} ${GIT_EXTERNAL_TARGET} ${PROJECT_NAME}-update-gitexternal update)
             set_target_properties(${_target} PROPERTIES
               EXCLUDE_FROM_DEFAULT_BUILD ON FOLDER git)
           endforeach()

doc/Changelog.md

@@ -1,7 +1,7 @@
 Changelog {#Changelog}
 =========
 
-# git master
+# Release 1.9.0 (09-Dec-2016)
 
 * [117](https://github.com/BlueBrain/Brion/pull/117):
   Changes and fixes in Brain Python module:

doc/feature/feature.md

@@ -1,8 +1,8 @@
-Feature specifications {#FeatureSpecs}
-======================
+RFCs {#rfcs}
+============
 
-* @subpage compartmentReport
-* @subpage compartmentReportMPI
+* @subpage compartment_report
+* @subpage compartment_report_mpi
 * @subpage morphology11
-* @subpage spikeReport
-* @subpage brainSynapses
+* @subpage spike_reports
+* @subpage brain_synapses

doc/python/CMakeLists.txt

@@ -10,12 +10,13 @@ endif()
 
 configure_file(conf.py.in ${PROJECT_BINARY_DIR}/doc/python/conf.py)
 
-file(COPY index.rst DESTINATION ${PROJECT_BINARY_DIR}/doc/python)
+file(COPY index.rst python_tutorial.rst
+  DESTINATION ${PROJECT_BINARY_DIR}/doc/python)
 
 add_custom_target(${PROJECT_NAME}-python-doc-html
   ${SPHINX_EXECUTABLE} -b html . ${PROJECT_BINARY_DIR}/doc/html/python
   WORKING_DIRECTORY ${PROJECT_BINARY_DIR}/doc/python
-  DEPENDS index.rst conf.py.in
+  DEPENDS index.rst python_tutorial.rst conf.py.in
   COMMENT "Generating Python documentation using Sphinx" VERBATIM)
 set_target_properties(${PROJECT_NAME}-python-doc-html PROPERTIES
   EXCLUDE_FROM_DEFAULT_BUILD ON FOLDER "doxygen")

doc/python/index.rst

@@ -6,6 +6,9 @@ Brain Python API documentation
 .. toctree::
    :maxdepth: 2
 
+This is the reference documention of the Brain Python API. For a quick
+introduction on the capabilities of this API check the :ref:`python_tutorial`.
+
 brain namespace
 ~~~~~~~~~~~~~~~
 .. automodule:: brain._brain