From 27b1ee1fbbdd71d1f6560f91325f8fbbee0342d8 Mon Sep 17 00:00:00 2001 From: Jochen Martin Eppler Date: Tue, 6 Feb 2018 15:54:34 +0100 Subject: [PATCH 1/8] Fix misleading indentation --- doc/CMakeLists.txt | 71 ++++++++++++++++++++++++---------------------- 1 file changed, 37 insertions(+), 34 deletions(-) diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 58c8d422c1..8f5a20400d 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -18,45 +18,48 @@ # along with NEST. If not, see . 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 ) + # 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" + ) + + # 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 () + endif () + endif () install( DIRECTORY conngen model_details From d28e4b0475e2b263c6679834c3830708777b0ced Mon Sep 17 00:00:00 2001 From: Jochen Martin Eppler Date: Tue, 6 Feb 2018 15:54:46 +0100 Subject: [PATCH 2/8] Add install-nodoc target as requested in #153 --- CMakeLists.txt | 4 +++ extras/help_generator/generate_help.py | 4 +++ extras/help_generator/generate_helpindex.py | 4 +++ extras/help_generator/helpers.py | 27 +++++++++++++++++++++ 4 files changed, 39 insertions(+) diff --git a/CMakeLists.txt b/CMakeLists.txt index 6774c3afad..fce1e1dbea 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -361,4 +361,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() diff --git a/extras/help_generator/generate_help.py b/extras/help_generator/generate_help.py index 7daf8320b2..6bee783d6a 100644 --- a/extras/help_generator/generate_help.py +++ b/extras/help_generator/generate_help.py @@ -34,6 +34,10 @@ from writers import coll_data from helpers import check_ifdef, create_helpdirs, cut_it +from helpers import help_generation_required + +if not help_generation_required(): + sys.exit(0) if len(sys.argv) != 3: print("Usage: python generate_help.py ") diff --git a/extras/help_generator/generate_helpindex.py b/extras/help_generator/generate_helpindex.py index 6490f39cfa..775cb40ed9 100644 --- a/extras/help_generator/generate_helpindex.py +++ b/extras/help_generator/generate_helpindex.py @@ -30,6 +30,10 @@ import os import sys from writers import write_helpindex +from helpers import help_generation_required + +if not help_generation_required(False): + sys.exit(0) if len(sys.argv) != 2: print("Usage: python generate_helpindex.py ") diff --git a/extras/help_generator/helpers.py b/extras/help_generator/helpers.py index 6d1e676cc5..48980483b0 100644 --- a/extras/help_generator/helpers.py +++ b/extras/help_generator/helpers.py @@ -77,3 +77,30 @@ def create_helpdirs(path): """ makedirs(os.path.join(path, 'sli')) makedirs(os.path.join(path, 'cc')) + + +def help_generation_required(print_msg = True): + """ + 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 os.environ.has_key("NEST_INSTALL_NODOC"): + if print_msg: + msg = "Not extracting help information due to 'make install-nodoc'." + print(blue + msg + noblue) + return False + else: + if print_msg: + msg = "Extracting help information. This may take a little while." + print(blue + msg + noblue) + return True From a53272a598e2b3e9f394e0241f0ada82d08ad9a4 Mon Sep 17 00:00:00 2001 From: Jochen Martin Eppler Date: Tue, 6 Feb 2018 17:22:01 +0100 Subject: [PATCH 3/8] Fix pep8 --- extras/help_generator/helpers.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/extras/help_generator/helpers.py b/extras/help_generator/helpers.py index 48980483b0..47b2dd71fe 100644 --- a/extras/help_generator/helpers.py +++ b/extras/help_generator/helpers.py @@ -78,8 +78,8 @@ def create_helpdirs(path): makedirs(os.path.join(path, 'sli')) makedirs(os.path.join(path, 'cc')) - -def help_generation_required(print_msg = True): + +def help_generation_required(print_msg=True): """ Check whether help extraction/installation is required. @@ -90,13 +90,13 @@ def help_generation_required(print_msg = 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 os.environ.has_key("NEST_INSTALL_NODOC"): + + if "NEST_INSTALL_NODOC" in os.environ: if print_msg: - msg = "Not extracting help information due to 'make install-nodoc'." + msg = "Not extracting help information with 'make install-nodoc'." print(blue + msg + noblue) return False else: From 2b16a06fdb3279dc0a210655f396de1936db90c5 Mon Sep 17 00:00:00 2001 From: Jochen Martin Eppler Date: Mon, 19 Feb 2018 04:08:03 +0100 Subject: [PATCH 4/8] Add information about `install-nodoc` to installation documentation --- INSTALL | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/INSTALL b/INSTALL index 8303e967e0..6be4faab33 100644 --- a/INSTALL +++ b/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 ======================= From 157c9d10e48dbfd6901afe492ed1b9eede6fe697 Mon Sep 17 00:00:00 2001 From: Jochen Martin Eppler Date: Thu, 5 Apr 2018 01:57:26 +0200 Subject: [PATCH 5/8] Fix install-nodoc target This makes the install-nodoc target work by first deleting the help directory, creating help for the install target, install the help directory if it was created, and generating the help index for the installed help directory if that exists. --- doc/CMakeLists.txt | 67 +++++++++++---------- extras/help_generator/generate_help.py | 9 ++- extras/help_generator/generate_helpindex.py | 4 -- extras/help_generator/helpers.py | 24 +++++--- extras/help_generator/writers.py | 4 ++ 5 files changed, 61 insertions(+), 47 deletions(-) diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 8f5a20400d..89afdb2bb5 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -17,45 +17,46 @@ # You should have received a copy of the GNU General Public License # along with NEST. If not, see . + 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. + # 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" - ) - - # 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\" - )" - ) + # 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 () diff --git a/extras/help_generator/generate_help.py b/extras/help_generator/generate_help.py index 3b4bba1223..2fa759e26e 100644 --- a/extras/help_generator/generate_help.py +++ b/extras/help_generator/generate_help.py @@ -35,11 +35,9 @@ 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 not help_generation_required(): - sys.exit(0) - if len(sys.argv) != 3: print("Usage: python generate_help.py ") sys.exit(1) @@ -47,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 = [] diff --git a/extras/help_generator/generate_helpindex.py b/extras/help_generator/generate_helpindex.py index 775cb40ed9..6490f39cfa 100644 --- a/extras/help_generator/generate_helpindex.py +++ b/extras/help_generator/generate_helpindex.py @@ -30,10 +30,6 @@ import os import sys from writers import write_helpindex -from helpers import help_generation_required - -if not help_generation_required(False): - sys.exit(0) if len(sys.argv) != 2: print("Usage: python generate_helpindex.py ") diff --git a/extras/help_generator/helpers.py b/extras/help_generator/helpers.py index 47b2dd71fe..4ab0a97099 100644 --- a/extras/help_generator/helpers.py +++ b/extras/help_generator/helpers.py @@ -21,6 +21,7 @@ import re import os +import shutil import errno @@ -79,7 +80,18 @@ def create_helpdirs(path): makedirs(os.path.join(path, 'cc')) -def help_generation_required(print_msg=True): +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. @@ -95,12 +107,10 @@ def help_generation_required(print_msg=True): noblue = "\033[0m" if "NEST_INSTALL_NODOC" in os.environ: - if print_msg: - msg = "Not extracting help information with 'make install-nodoc'." - print(blue + msg + noblue) + msg = "Not extracting help information for target 'install-nodoc'." + print(blue + msg + noblue) return False else: - if print_msg: - msg = "Extracting help information. This may take a little while." - print(blue + msg + noblue) + msg = "Extracting help information. This may take a little while." + print(blue + msg + noblue) return True diff --git a/extras/help_generator/writers.py b/extras/help_generator/writers.py index 350ad3aeff..2f9d840a73 100644 --- a/extras/help_generator/writers.py +++ b/extras/help_generator/writers.py @@ -152,6 +152,10 @@ def write_helpindex(helpdir): --------------------------------------- """ + + if not os.path.exists(helpdir): + return + filelist = glob.glob(os.path.join(helpdir, '*', '*.hlp')) html_list = [] hlp_list = [] From cf8e1ce6b67a6adcd483c5bc0702e6004c5a794c Mon Sep 17 00:00:00 2001 From: Jochen Martin Eppler Date: Thu, 5 Apr 2018 03:38:13 +0200 Subject: [PATCH 6/8] Fix formatting errors --- extras/help_generator/README.md | 2 +- extras/help_generator/writers.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/extras/help_generator/README.md b/extras/help_generator/README.md index 692b91321e..ebf8ea42db 100644 --- a/extras/help_generator/README.md +++ b/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. \ No newline at end of file +and converts it into .html and .hlp files. diff --git a/extras/help_generator/writers.py b/extras/help_generator/writers.py index 2f9d840a73..d4d278169e 100644 --- a/extras/help_generator/writers.py +++ b/extras/help_generator/writers.py @@ -155,7 +155,7 @@ def write_helpindex(helpdir): if not os.path.exists(helpdir): return - + filelist = glob.glob(os.path.join(helpdir, '*', '*.hlp')) html_list = [] hlp_list = [] From 3903563a15391641418a538962dfb58f3dd311c9 Mon Sep 17 00:00:00 2001 From: Jochen Martin Eppler Date: Thu, 5 Apr 2018 14:21:54 +0200 Subject: [PATCH 7/8] Add comment and only use tabs for indentation --- doc/CMakeLists.txt | 23 +++++++++++------------ extras/help_generator/writers.py | 1 + 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 89afdb2bb5..ed059d6a12 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -30,27 +30,26 @@ if ( NOT CMAKE_CROSSCOMPILING ) # 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 + # 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" + # 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 + OPTIONAL ) - # Update the global help index to include all help files in - # the global installation directory for - # documentation. - install( CODE + # 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\" diff --git a/extras/help_generator/writers.py b/extras/help_generator/writers.py index d4d278169e..e3a6822363 100644 --- a/extras/help_generator/writers.py +++ b/extras/help_generator/writers.py @@ -153,6 +153,7 @@ def write_helpindex(helpdir): """ + # We only have to generate a helpindex if the help directoy exists if not os.path.exists(helpdir): return From 28a0cdf40ddaf053a891286dc00300946f53813a Mon Sep 17 00:00:00 2001 From: Hans Ekkehard Plesser Date: Thu, 5 Apr 2018 14:25:10 +0200 Subject: [PATCH 8/8] Update writers.py --- extras/help_generator/writers.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extras/help_generator/writers.py b/extras/help_generator/writers.py index e3a6822363..ff021249ed 100644 --- a/extras/help_generator/writers.py +++ b/extras/help_generator/writers.py @@ -153,7 +153,7 @@ def write_helpindex(helpdir): """ - # We only have to generate a helpindex if the help directoy exists + # We only have to generate a helpindex if the help directory exists if not os.path.exists(helpdir): return