Help: Add option to create and install Qt .qch file.

Utilities/Sphinx/CMakeLists.txt

@@ -24,6 +24,7 @@ project(CMakeHelp NONE)
 
 option(SPHINX_MAN "Build man pages with Sphinx" OFF)
 option(SPHINX_HTML "Build html 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
@@ -32,7 +33,7 @@ find_program(SPHINX_EXECUTABLE
 
 mark_as_advanced(SPHINX_TEXT)
 
-if(NOT SPHINX_MAN AND NOT SPHINX_HTML AND NOT SPHINX_TEXT)
+if(NOT SPHINX_MAN AND NOT SPHINX_HTML AND NOT SPHINX_QTHELP AND NOT SPHINX_TEXT)
   return()
 elseif(NOT SPHINX_EXECUTABLE)
   message(FATAL_ERROR "SPHINX_EXECUTABLE (sphinx-build) is not found!")
@@ -63,6 +64,21 @@ 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
+    COMMAND qcollectiongenerator ${CMAKE_CURRENT_BINARY_DIR}/qthelp/CMake.qhcp
+  )
+endif()
+
 
 set(doc_format_outputs "")
 set(doc_format_last "")
@@ -78,6 +94,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
@@ -122,3 +139,8 @@ if(SPHINX_HTML)
           PATTERN objects.inv EXCLUDE
           )
 endif()
+if(SPHINX_QTHELP)
+  install(FILES ${CMAKE_CURRENT_BINARY_DIR}/qthelp/CMake.qch
+          DESTINATION ${CMAKE_DOC_DIR}
+          )
+endif()

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