Merge branch 'master' into doc-singlehtml

Resolve conflicts in Utilities/Sphinx/CMakeLists.txt by adding the help
options from both sides.

Utilities/Sphinx/CMakeLists.txt

@@ -25,6 +25,7 @@ project(CMakeHelp NONE)
 option(SPHINX_MAN "Build man pages with Sphinx" OFF)
 option(SPHINX_HTML "Build html help with Sphinx" OFF)
 option(SPHINX_SINGLEHTML "Build html single page help with Sphinx" OFF)
+option(SPHINX_QTHELP "Build Qt help with Sphinx" OFF)
 option(SPHINX_TEXT "Build text help with Sphinx (not installed)" OFF)
 find_program(SPHINX_EXECUTABLE
   NAMES sphinx-build
@@ -33,7 +34,7 @@ find_program(SPHINX_EXECUTABLE
 
 mark_as_advanced(SPHINX_TEXT)
 
-if(NOT SPHINX_MAN AND NOT SPHINX_HTML AND NOT SPHINX_SINGLEHTML AND NOT SPHINX_TEXT)
+if(NOT SPHINX_MAN AND NOT SPHINX_HTML AND NOT SPHINX_SINGLEHTML AND NOT SPHINX_QTHELP AND NOT SPHINX_TEXT)
   return()
 elseif(NOT SPHINX_EXECUTABLE)
   message(FATAL_ERROR "SPHINX_EXECUTABLE (sphinx-build) is not found!")
@@ -67,6 +68,30 @@ endif()
 if(SPHINX_TEXT)
   list(APPEND doc_formats text)
 endif()
+if(SPHINX_QTHELP)
+  find_program(QCOLLECTIONGENERATOR_EXECUTABLE
+    NAMES qcollectiongenerator
+    DOC "qcollectiongenerator tool"
+    )
+  if (NOT QCOLLECTIONGENERATOR_EXECUTABLE)
+    message(FATAL_ERROR "QCOLLECTIONGENERATOR_EXECUTABLE (qcollectiongenerator) not found!")
+  endif()
+  list(APPEND doc_formats qthelp)
+
+  set(qthelp_extra_commands
+    # Workaround for assistant prior to
+    # https://codereview.qt-project.org/#change,82250 in Qt 4.
+    COMMAND ${CMAKE_COMMAND} "-DCSS_DIR=${CMAKE_CURRENT_BINARY_DIR}/qthelp/_static"
+      -P "${CMAKE_CURRENT_SOURCE_DIR}/apply_qthelp_css_workaround.cmake"
+    # Workaround sphinx configurability:
+    # https://bitbucket.org/birkenfeld/sphinx/issue/1448/make-qthelp-more-configurable
+    COMMAND ${CMAKE_COMMAND} "-DQTHELP_DIR=${CMAKE_CURRENT_BINARY_DIR}/qthelp/"
+      "-DCMake_VERSION=${CMake_VERSION_MAJOR}${CMake_VERSION_MINOR}${CMake_VERSION_PATCH}"
+      -P "${CMAKE_CURRENT_SOURCE_DIR}/fixup_qthelp_names.cmake"
+    COMMAND qcollectiongenerator ${CMAKE_CURRENT_BINARY_DIR}/qthelp/CMake.qhcp
+  )
+endif()
+
 
 set(doc_format_outputs "")
 set(doc_format_last "")
@@ -82,6 +107,7 @@ foreach(format ${doc_formats})
             ${CMake_SOURCE_DIR}/Help
             ${CMAKE_CURRENT_BINARY_DIR}/${format}
             > ${doc_format_log} # log stdout, pass stderr
+    ${${format}_extra_commands}
     DEPENDS ${doc_format_last}
     COMMENT "sphinx-build ${format}: see Utilities/Sphinx/${doc_format_log}"
     VERBATIM
@@ -134,3 +160,9 @@ if(SPHINX_SINGLEHTML)
           PATTERN objects.inv EXCLUDE
           )
 endif()
+
+if(SPHINX_QTHELP)
+  install(FILES ${CMAKE_CURRENT_BINARY_DIR}/qthelp/CMake-${CMake_VERSION_MAJOR}${CMake_VERSION_MINOR}${CMake_VERSION_PATCH}.qch
+          DESTINATION ${CMAKE_DOC_DIR}
+          )
+endif()

Utilities/Sphinx/apply_qthelp_css_workaround.cmake

@@ -0,0 +1,15 @@
+
+file(READ "${CSS_DIR}/basic.css" BasicCssContent)
+
+file(READ "${CSS_DIR}/default.css" DefaultCssContent)
+string(REPLACE
+  "@import url(\"basic.css\")" "${BasicCssContent}"
+  DefaultCssContent "${DefaultCssContent}"
+)
+
+file(READ "${CSS_DIR}/cmake.css" CMakeCssContent)
+string(REPLACE
+  "@import url(\"default.css\")" "${DefaultCssContent}"
+  CMakeCssContent "${CMakeCssContent}"
+)
+file(WRITE "${CSS_DIR}/cmake.css" "${CMakeCssContent}")

Utilities/Sphinx/cmake.py

@@ -21,6 +21,24 @@ from pygments.lexer import bygroups
 CMakeLexer.tokens["args"].append(('(\\$<)(.+?)(>)',
                                   bygroups(Operator, Name.Variable, Operator)))
 
+# Monkey patch for sphinx generating invalid content for qcollectiongenerator
+# https://bitbucket.org/birkenfeld/sphinx/issue/1435/qthelp-builder-should-htmlescape-keywords
+from sphinx.util.pycompat import htmlescape
+from sphinx.builders.qthelp import QtHelpBuilder
+old_build_keywords = QtHelpBuilder.build_keywords
+def new_build_keywords(self, title, refs, subitems):
+  old_items = old_build_keywords(self, title, refs, subitems)
+  new_items = []
+  for item in old_items:
+    before, rest = item.split("ref=\"", 1)
+    ref, after = rest.split("\"")
+    if ("<" in ref and ">" in ref):
+      new_items.append(before + "ref=\"" + htmlescape(ref) + "\"" + after)
+    else:
+      new_items.append(item)
+  return new_items
+QtHelpBuilder.build_keywords = new_build_keywords
+
 
 from docutils.parsers.rst import Directive, directives
 from docutils.transforms import Transform

Utilities/Sphinx/conf.py.in

@@ -61,3 +61,7 @@ html_theme = 'default'
 html_title = 'CMake %s Documentation' % release
 html_short_title = '%s Documentation' % release
 html_favicon = 'cmake-favicon.ico'
+# Not supported yet by sphinx:
+# https://bitbucket.org/birkenfeld/sphinx/issue/1448/make-qthelp-more-configurable
+# qthelp_namespace = "org.cmake"
+# qthelp_qch_name = "CMake-300.qch"

Utilities/Sphinx/fixup_qthelp_names.cmake

@@ -0,0 +1,32 @@
+
+file(READ "${QTHELP_DIR}/CMake.qhcp" QHCP_CONTENT)
+
+string(REPLACE
+  "<homePage>qthelp://org.sphinx.cmake" "<homePage>qthelp://org.cmake"
+  QHCP_CONTENT "${QHCP_CONTENT}"
+)
+string(REPLACE
+  "<startPage>qthelp://org.sphinx.cmake" "<startPage>qthelp://org.cmake"
+  QHCP_CONTENT "${QHCP_CONTENT}"
+)
+
+string(REPLACE
+  "<output>CMake.qch" "<output>CMake-${CMake_VERSION}.qch"
+  QHCP_CONTENT "${QHCP_CONTENT}"
+)
+string(REPLACE
+  "<file>CMake.qch" "<file>CMake-${CMake_VERSION}.qch"
+  QHCP_CONTENT "${QHCP_CONTENT}"
+)
+
+file(WRITE "${QTHELP_DIR}/CMake.qhcp" "${QHCP_CONTENT}")
+
+
+file(READ "${QTHELP_DIR}/CMake.qhp" QHP_CONTENT)
+
+string(REPLACE
+  "<namespace>org.sphinx.cmake" "<namespace>org.cmake"
+  QHP_CONTENT "${QHP_CONTENT}"
+)
+
+file(WRITE "${QTHELP_DIR}/CMake.qhp" "${QHP_CONTENT}")