Add 'install-nodoc' target for make

CMakeLists.txt

@@ -355,4 +355,8 @@ install( FILES LICENSE README.md NEWS
     DESTINATION ${CMAKE_INSTALL_DOCDIR}
     )
 
+add_custom_target( install-nodoc
+  COMMAND make NEST_INSTALL_NODOC=true install
+)
+
 nest_print_config_summary()

INSTALL

@@ -15,6 +15,11 @@ should build and install NEST to `/install/path`, which should be an absolute
 path. Detailed installation  instructions can be found below, including 
 instructions for macOS, BlueGene/Q and Fujitsu Sparc64 systems.
 
+On systems where help extraction is slow, the call to `make install` can be replaced
+by `make install-nodoc` to skip the generation of help pages and indices. Using this
+option can help developers to speed up development cycles, but is not recommended for
+production use as it renders the built-in help system useless.
+
 Choice of CMake Version
 =======================
 

doc/CMakeLists.txt

@@ -17,46 +17,49 @@
 # You should have received a copy of the GNU General Public License
 # along with NEST.  If not, see <http://www.gnu.org/licenses/>.
 
+
 if ( NOT CMAKE_CROSSCOMPILING )
-  add_custom_target( generate_help ALL )
-
-    # Python is needed to generate the help. If Python does not exist, there are
-    # problems with the following.
-    # See https://github.com/nest/nest-simulator/issues/678.
-    find_package( PythonInterp )
-    if ( PYTHONINTERP_FOUND )
-
-      # Because of problems of help generation with the implementation of 're'
-      # in Python older than 2.7.8, the production of the help is skipped
-      # completely for these versions.
-      if(${PYTHON_VERSION_STRING} VERSION_GREATER "2.7.7")
-          # Extract help from all source files in the source code, put them in
-          # doc/help and generate a local help index in the build directory containing
-          # links to the help files.
-          add_custom_command( TARGET generate_help POST_BUILD
-            COMMAND ${PYTHON_EXECUTABLE} -B generate_help.py "${PROJECT_SOURCE_DIR}"
-            "${PROJECT_BINARY_DIR}"
-            COMMAND ${PYTHON_EXECUTABLE} -B generate_helpindex.py "${PROJECT_BINARY_DIR}/doc"
-            WORKING_DIRECTORY "${PROJECT_SOURCE_DIR}/extras/help_generator"
-            COMMENT "Extracting help information; this may take a litte while."
-            )
-          # Copy the local doc/help directory to the global installation
-          # directory for documentation.
-          install( DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/help"
-            DESTINATION "${CMAKE_INSTALL_DOCDIR}"
-            )
-          # Update the global help index to contain all help files that are
-          # located in the global installation directory for documentation.
-          install( CODE
-            "execute_process(
-              COMMAND ${PYTHON_EXECUTABLE} -B generate_helpindex.py \"${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_DOCDIR}\"
-              WORKING_DIRECTORY \"${PROJECT_SOURCE_DIR}/extras/help_generator\"
-            )"
-            )
-      endif ()
+
+  # Python is needed to generate the help. If Python does not exist,
+  # there are problems with the following.
+  # See https://github.com/nest/nest-simulator/issues/678.
+  find_package( PythonInterp )
+  if ( PYTHONINTERP_FOUND )
+
+    # We skip help generation for Python versions < 2.7.8 due to
+    # problems with implementation of 're' in those.
+    if( ${PYTHON_VERSION_STRING} VERSION_GREATER "2.7.7" )
+
+        # Extract help from all source files in the source code, put
+        # them in doc/help and generate a local help index in the
+        # build directory containing links to the help files.
+        install( CODE
+          "execute_process(
+             COMMAND ${PYTHON_EXECUTABLE} -B generate_help.py \"${PROJECT_SOURCE_DIR}\" \"${PROJECT_BINARY_DIR}\"
+             WORKING_DIRECTORY \"${PROJECT_SOURCE_DIR}/extras/help_generator\"
+             )"
+          )
+
+        # Copy the local doc/help directory to the global installation
+        # directory for documentation.
+        install( DIRECTORY "${PROJECT_BINARY_DIR}/doc/help"
+          DESTINATION "${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_DOCDIR}"
+          OPTIONAL
+          )
+
+        # Update the global help index to include all help files in
+        # the global installation directory for documentation.
+        install( CODE
+          "execute_process(
+             COMMAND ${PYTHON_EXECUTABLE} -B generate_helpindex.py \"${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_DOCDIR}\"
+             WORKING_DIRECTORY \"${PROJECT_SOURCE_DIR}/extras/help_generator\"
+             )"
+          )
 
     endif ()
 
+  endif ()
+
 endif ()
 
 install( DIRECTORY conngen model_details

extras/help_generator/README.md

@@ -1,4 +1,4 @@
 # README for the NEST help generator
 
 The parser goes through all .sli and .cc files to find documentation
-and converts it into .html and .hlp files.
+and converts it into .html and .hlp files.

extras/help_generator/generate_help.py

@@ -35,6 +35,8 @@
 
 from writers import coll_data
 from helpers import check_ifdef, create_helpdirs, cut_it
+from helpers import delete_helpdir
+from helpers import help_generation_required
 
 if len(sys.argv) != 3:
     print("Usage: python generate_help.py <source_dir> <build_dir>")
@@ -43,6 +45,11 @@
 source_dir, build_dir = sys.argv[1:]
 
 helpdir = os.path.join(build_dir, "doc", "help")
+delete_helpdir(helpdir)
+
+if not help_generation_required():
+    sys.exit(0)
+
 create_helpdirs(helpdir)
 
 allfiles = []

extras/help_generator/helpers.py

@@ -21,6 +21,7 @@
 
 import re
 import os
+import shutil
 import errno
 
 
@@ -77,3 +78,39 @@ def create_helpdirs(path):
     """
     makedirs(os.path.join(path, 'sli'))
     makedirs(os.path.join(path, 'cc'))
+
+
+def delete_helpdir(path):
+    """
+    Delete the directories for the help files.
+    """
+    try:
+        shutil.rmtree(path)
+    except OSError as exc:
+        if exc.errno != errno.ENOENT:
+            raise
+
+
+def help_generation_required():
+    """
+    Check whether help extraction/installation is required.
+
+    The check is based on the setting of the environment variable
+    NEST_INSTALL_NODOC. If the variable is set, this function returns
+    False, if not, it returns True.
+
+    A corresponding message is printed if print_msg is True. The
+    message is omitted if print_msg is set to False.
+    """
+
+    blue = "\033[94m"
+    noblue = "\033[0m"
+
+    if "NEST_INSTALL_NODOC" in os.environ:
+        msg = "Not extracting help information for target 'install-nodoc'."
+        print(blue + msg + noblue)
+        return False
+    else:
+        msg = "Extracting help information. This may take a little while."
+        print(blue + msg + noblue)
+        return True

extras/help_generator/writers.py

@@ -152,6 +152,11 @@ def write_helpindex(helpdir):
     ---------------------------------------
 
     """
+
+    # We only have to generate a helpindex if the help directory exists
+    if not os.path.exists(helpdir):
+        return
+
     filelist = glob.glob(os.path.join(helpdir, '*', '*.hlp'))
     html_list = []
     hlp_list = []