Add docs for CoreNEURON (#359)

Similar to NMODL, add documentation for CoreNEURON
with doxygen and Sphinx.

Author: alexsavulescu

.travis.yml

@@ -17,6 +17,7 @@ matrix:
       dist: xenial
       env:
         - cmake_option="-DCORENRN_ENABLE_MPI=ON"
+        - BUILD_DOCUMENTATION=ON
     - os: linux
       dist: xenial
       env:
@@ -84,6 +85,7 @@ addons:
     sources:
       - ubuntu-toolchain-r-test
     packages:
+      - doxygen
       - bison
       - flex
       - libboost-all-dev
@@ -105,6 +107,15 @@ addons:
 # Set up environments
 #=============================================================================
 before_install:
+  # quickly return if this is a docs-only PR
+  - |
+    if [ "${TRAVIS_PULL_REQUEST}" != "false" ]; then
+      if ! git diff --name-only ${TRAVIS_COMMIT_RANGE} | grep -qvE '(\.md)$|(\.txt)$|^(docs/)' ; then
+        echo "Skipping CI build since we have docs-only changes for ${TRAVIS_COMMIT_RANGE} :"
+        git diff --name-only ${TRAVIS_COMMIT_RANGE}
+        exit
+      fi
+    fi
   # brew installed flex and bison is not in $PATH
   # unlink python2 and use python3 as it's required for nmodl
   - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
@@ -114,27 +125,36 @@ before_install:
     else
         pyenv global $PYTHON_VERSION;
     fi
-  # install NMODL dependencies
-  - if [[ "$USE_NMODL" == "ON" || "$USE_ISPC" == "ON" ]]; then
-        pip3 install jinja2 pyyaml pytest "sympy<1.6";
-    fi
   - if [ -n "$GCC_VERSION" ]; then
         export CXX="g++-${GCC_VERSION}" CC="gcc-${GCC_VERSION}";
         $CXX --version;
     fi
+
+install:
   # install ISPC compiler (only for mac or linux build for now)
   - if [[ "$USE_ISPC" == "ON" ]]; then
-        ispc_version="v1.12.0";
-        if [ "$TRAVIS_OS_NAME" == "linux" ]; then
-            url_os="linux";
-            ispc_version_suffix="b";
-        else
-            url_os="macOS";
-            ispc_version_suffix="";
-        fi;
-        url="https://github.com/ispc/ispc/releases/download/${ispc_version}/ispc-${ispc_version}${ispc_version_suffix}-${url_os}.tar.gz";
-        wget -O ispc.tar.gz $url;
-        mkdir ispc && tar -xvzf ispc.tar.gz -C ispc --strip 1;
+      ispc_version="v1.12.0";
+      if [ "$TRAVIS_OS_NAME" == "linux" ]; then
+        url_os="linux";
+        ispc_version_suffix="b";
+      else
+        url_os="macOS";
+        ispc_version_suffix="";
+      fi;
+      url="https://github.com/ispc/ispc/releases/download/${ispc_version}/ispc-${ispc_version}${ispc_version_suffix}-${url_os}.tar.gz";
+      wget -O ispc.tar.gz $url;
+      mkdir ispc && tar -xvzf ispc.tar.gz -C ispc --strip 1;
+    fi
+
+  # install NMODL dependencies
+  - if [[ "$USE_NMODL" == "ON" || "$USE_ISPC" == "ON" ]]; then
+      pip3 install --upgrade pip;
+      pip3 install jinja2 pyyaml pytest "sympy<1.6";
+    fi
+  # install documentation dependencies
+  - if [ "$BUILD_DOCUMENTATION" = "ON" ] && [ "$TRAVIS_OS_NAME" == "linux" ]; then
+      pip3 install --upgrade pip;
+      pip3 install --user -r docs/docs_requirements.txt --upgrade;
     fi
 #=============================================================================
 # Build, test and install
@@ -154,3 +174,32 @@ script:
   - cmake --build .
   - ctest --output-on-failure
   - make install
+
+
+#=============================================================================
+# Prepare Documentation
+#=============================================================================
+after_success:
+  - if [ "$BUILD_DOCUMENTATION" = "ON" ] && [ "$TRAVIS_OS_NAME" == "linux" ]; then
+      echo "------- Build Doxygen Documentation -------";
+      pushd $TRAVIS_BUILD_DIR/build;
+      make docs;
+      echo "-------- Disable jekyll --------";
+      pushd $TRAVIS_BUILD_DIR/build/docs;
+      touch .nojekyll;
+    fi
+
+
+#=============================================================================
+# Documentation deployment
+#=============================================================================
+deploy:
+  provider: pages
+  skip_cleanup: true
+  github_token: $GITHUB_TOKEN
+  keep_history: false
+  local_dir: $TRAVIS_BUILD_DIR/build/docs
+  target_branch: gh-pages
+  on:
+    branch: master
+    condition: $BUILD_DOCUMENTATION = ON && $TRAVIS_OS_NAME = linux

CMake/packages/FindSphinx.cmake

@@ -0,0 +1,9 @@
+find_program(SPHINX_EXECUTABLE
+        NAMES sphinx-build
+        DOC "/path/to/sphinx-build")
+
+include(FindPackageHandleStandardArgs)
+
+find_package_handle_standard_args(Sphinx
+        "Failed to find sphinx-build executable"
+        SPHINX_EXECUTABLE)

CMakeLists.txt

@@ -278,6 +278,59 @@ else()
 endif()
 
 
+# =============================================================================
+# Setup Doxygen documentation
+# =============================================================================
+find_package(Doxygen QUIET)
+if(DOXYGEN_FOUND)
+  # generate Doxyfile with correct source paths
+  configure_file(${PROJECT_SOURCE_DIR}/docs/Doxyfile.in ${PROJECT_BINARY_DIR}/Doxyfile)
+  add_custom_target(
+          doxygen
+          COMMAND ${DOXYGEN_EXECUTABLE} ${PROJECT_BINARY_DIR}/Doxyfile
+          WORKING_DIRECTORY ${PROJECT_BINARY_DIR}
+          COMMENT "Generating API documentation with Doxygen"
+          VERBATIM)
+endif()
+
+# =============================================================================
+# Setup Sphinx documentation
+# =============================================================================
+find_package(Sphinx QUIET)
+if(SPHINX_FOUND)
+  set(SPHINX_SOURCE ${PROJECT_SOURCE_DIR}/docs)
+  set(SPHINX_BUILD ${PROJECT_BINARY_DIR}/docs/)
+
+  add_custom_target(
+          sphinx
+          COMMAND ${SPHINX_EXECUTABLE} -b html
+          ${SPHINX_SOURCE} ${SPHINX_BUILD}
+          WORKING_DIRECTORY ${PROJECT_BINARY_DIR}
+          COMMENT "Generating documentation with Sphinx"
+  )
+endif()
+
+# =============================================================================
+# Build full docs
+# =============================================================================
+if(DOXYGEN_FOUND AND SPHINX_FOUND)
+  add_custom_target(
+          docs
+          COMMAND make doxygen
+          WORKING_DIRECTORY ${PROJECT_BINARY_DIR}
+          COMMAND make sphinx
+          WORKING_DIRECTORY ${PROJECT_BINARY_DIR}
+          COMMENT "Generating full documentation"
+  )
+else()
+  add_custom_target(
+          docs
+          VERBATIM COMMAND echo "Please install docs requirements (see docs/README.md)!"
+          COMMENT "Documentation generation not possible!"
+  )
+endif()
+
+
 # =============================================================================
 # Build status
 # =============================================================================
@@ -291,6 +344,7 @@ if(cmake_generator_tolower MATCHES "makefile")
   message(STATUS "Command             |   Description")
   message(STATUS "--------------------+--------------------------------------------------------")
   message(STATUS "make install        | Will install CoreNEURON to: ${CMAKE_INSTALL_PREFIX}")
+  message(STATUS "make docs           | Build full docs. Calls targets: doxygen, sphinx")
   message(STATUS "--------------------+--------------------------------------------------------")
   message(STATUS " Build option       | Status")
   message(STATUS "--------------------+--------------------------------------------------------")