Qt Creator help/documentation file for Clang

[kwk]

Summary

In D2967 I've proposed a change to generate a Qt Compressed Help file for the LLVM source code.

As a consequence, this change brings the same capabilities to Clang while reusing these two variables:

LLVM_ENABLE_DOXYGEN_QT_HELP
LLVM_DOXYGEN_QHELPGENERATOR_PATH

and adding

CLANG_DOXYGEN_QCH_FILENAME="org.llvm.clang.qch"
CLANG_DOXYGEN_QHP_NAMESPACE="org.llvm.clang"
CLANG_DOXYGEN_QHP_CUST_FILTER_NAME="Clang ${CLANG_VERSION}"
CLANG_DOXYGEN_QHP_CUST_FILTER_ATTRS="Clang,${CLANG_VERSION}"

Regards,
Konrad

[gribozavr]

Please document these build parameters somewhere.

[kwk]

Here's a screenshot of how the generated documentation file org.llvm.clang.qch looks like in Qt Creator. Here,

{F46626}

[kwk]

docs/doxygen.cfg.in

753–761

These comment lines for GENERATE_ECLIPSEHELP are not needed. I accidentally committed them.

[kwk]

Hi gribozavr,

in which place shall I document the build variables? The options and variables I've added all have a descriptions string that shows up in in the cmake-gui command.

I ran this command:

find . -name "CMakeLists.txt" | xargs rgrep "CLANG_[A-Z0-9_]*" -o --no-filename | sort | uniq -c | sort -n

to get this list of CLANG_* identifiers from the CMakeLists.txt files:

 1 CLANG_DOC_QCH_FILENAME
 1 CLANG_DOC_QHELPGENERATOR_PATH
 1 CLANG_DOC_QHP_NAMESPACE
 1 CLANG_GENERATE_QHP
 1 CLANG_RESOURCE_DIR
 1 CLANG_TOOLS_BINARY_DIR
 1 CLANG_TOOLS_EXTRA_SOURCE_DIR
 1 CLANG_TOOLS_SOURCE_DIR
 1 CLANG_VERSION_PATCHLEVEL
 2 CLANG_BINARY_DIR
 2 CLANG_BUILD_STATIC
 2 CLANG_DOC_GENERATE_QCH
 2 CLANG_DOC_GENERATE_QHP
 2 CLANG_EXAMPLES
 2 CLANG_FORMAT_VS_PLUGIN
 2 CLANG_GENERATE_QCH
 2 CLANG_HAS_VERSION_PATCHLEVEL
 2 CLANG_HAVE_LIBXML
 2 CLANG_INCLUDE_DOCS
 2 CLANG_INCLUDE_TESTS
 2 CLANG_LINT_SOURCE_DIR
 2 CLANG_MODERNIZE_SOURCE_DIR
 2 CLANG_TEST_USE_VG
 2 CLANG_TOOLS_DIR
 2 CLANG_TOOLS_TEST_DEPS
 2 CLANG_TOOLS_TEST_EXTRA_ARGS
 2 CLANG_TOOLS_TEST_USE_VG
 2 CLANG_VENDOR_UTI
 3 CLANG_BUILD_EXAMPLES
 3 CLANG_BUILT_STANDALONE
 3 CLANG_EXECUTABLE_VERSION
 3 CLANG_ORDER_FILE
 3 CLANG_TEST_PARAMS
 3 CLANG_VERSION_MAJOR
 3 CLANG_VERSION_MINOR
 4 CLANG_LIBRARY_VERSION
 4 CLANG_LINK_FLAGS
 4 CLANG_REPOSITORY_STRING
 4 CLANG_TABLEGEN_TARGETS
 4 CLANG_TEST_EXTRA_ARGS
 5 CLANG_TEST_DEPS
 6 CLANG_VENDOR
 8 CLANG_ENABLE_ARCMT
 8 CLANG_ENABLE_REWRITER
10 CLANG_ENABLE_STATIC_ANALYZER
11 CLANG_VERSION
12 CLANG_SOURCE_DIR

When I search for one of them, they only occur in CMakeLists.txt files themselves. For example:

grep "CLANG_ENABLE_ARCMT" . -r --context=5

And in the context ofr 5 lines before and after the match I couldn't find any more documentation than the description that I've added as well.

This isn't meant as an excuse but I'd really like to know in what other places to the build parameters.

[kwk]

Based on D2967 I plan to modify this patch.

[kwk]

This change uses the already exising CMake option LLVM_ENABLE_DOXYGEN_QT_HELP
to check whether a Qt Compressed Help file shall be generated. Also, the path
to the qhelpgenerator binary is reused (LLVM_DOXYGEN_QHELPGENERATOR_PATH).

This change depends on revision rL203272 of the LLVM source.

[gottesmm]

One question, otherwise this looks fine to me. I defer of course to other gribozavr if he has any opinions.

docs/CMakeLists.txt

29

I noticed that the previous namespace was org.llvm. Is that correct? Will that cause any conflicts/etc? I don't know that much about QHP, but it just seems like an obvious question.

[kwk]

docs/CMakeLists.txt

29

Both QHP files, the one for LLVM and the Clang one, need to have distinct namespaces, otherwise they cannot be imported by a viewing application like Qt Creator. Therefore, it's correct to pick org.llvm.clang as namespace for the CLANG QHP file.

[kwk]

Since the CMake variables LLVM_ENABLE_DOXYGEN_QT_HELP and LLVM_DOXYGEN_QHELPGENERATOR_PATH are already documented in $LLVM/docs/CMake.rst, I think the most important parts are covered.

[gottesmm]

Alright sounds good to me.

[gribozavr]

Committed r203801.

docs/CMakeLists.txt

if (LLVM_DOXYGEN_EXTERNAL_SEARCH)
     set(extra_search_mappings "${LLVM_DOXYGEN_SEARCH_MAPPINGS}")
   else()
     set(enable_searchengine "NO")
     set(searchengine_url "")
     set(enable_server_based_search "NO")
     set(enable_external_search "NO")
     set(extra_search_mappings "")
   endif()
   
+  # If asked, configure doxygen for the creation of a Qt Compressed Help file.
+  if (LLVM_ENABLE_DOXYGEN_QT_HELP)
+    set(CLANG_DOXYGEN_QCH_FILENAME "org.llvm.clang.qch" CACHE STRING
+      "Filename of the Qt Compressed help file")
+    set(CLANG_DOXYGEN_QHP_NAMESPACE "org.llvm.clang" CACHE STRING 
+      "Namespace under which the intermediate Qt Help Project file lives")
+    set(CLANG_DOXYGEN_QHP_CUST_FILTER_NAME "Clang ${CLANG_VERSION}" CACHE STRING
+      "See http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters")
+    set(CLANG_DOXYGEN_QHP_CUST_FILTER_ATTRS "Clang,${CLANG_VERSION}" CACHE STRING
+      "See http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes")
+    set(clang_doxygen_generate_qhp "YES")
+    set(clang_doxygen_qch_filename "${CLANG_DOXYGEN_QCH_FILENAME}")
+    set(clang_doxygen_qhp_namespace "${CLANG_DOXYGEN_QHP_NAMESPACE}")
+    set(clang_doxygen_qhelpgenerator_path "${LLVM_DOXYGEN_QHELPGENERATOR_PATH}")
+    set(clang_doxygen_qhp_cust_filter_name "${CLANG_DOXYGEN_QHP_CUST_FILTER_NAME}")
+    set(clang_doxygen_qhp_cust_filter_attrs "${CLANG_DOXYGEN_QHP_CUST_FILTER_ATTRS}")
+  else()
+    set(clang_doxygen_generate_qhp "NO")
+    set(clang_doxygen_qch_filename "")
+    set(clang_doxygen_qhp_namespace "")
+    set(clang_doxygen_qhelpgenerator_path "")
+    set(clang_doxygen_qhp_cust_filter_name "")
+    set(clang_doxygen_qhp_cust_filter_attrs "")
+  endif()
+
   configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doxygen.cfg.in
     ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg @ONLY)
 
   set(abs_top_srcdir)
   set(abs_top_builddir)
   set(DOT)
   set(enable_searchengine)
   set(searchengine_url)
   set(enable_server_based_search)
   set(enable_external_search)
   set(extra_search_mappings)
+  set(clang_doxygen_generate_qhp)
+  set(clang_doxygen_qch_filename)
+  set(clang_doxygen_qhp_namespace)
+  set(clang_doxygen_qhelpgenerator_path)
+  set(clang_doxygen_qhp_cust_filter_name)
+  set(clang_doxygen_qhp_cust_filter_attrs)
 
   add_custom_target(doxygen-clang
     COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg
     WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
     COMMENT "Generating clang doxygen documentation." VERBATIM)
 
   if (LLVM_BUILD_DOCS)
     add_dependencies(doxygen doxygen-clang)
   endif()
 
   if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY)
     install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doxygen/html
       DESTINATION docs/html)
   endif()
 endif()
 endif()

docs/doxygen.cfg.in

 
 BINARY_TOC             = NO
 
 # The TOC_EXPAND flag can be set to YES to add extra items for group members 
 # to the contents of the HTML help documentation and to the tree view.
 
 TOC_EXPAND             = NO
 
+# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and 
+# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated 
+# that can be used as input for Qt's qhelpgenerator to generate a 
+# Qt Compressed Help (.qch) of the generated HTML documentation.
+
+GENERATE_QHP           = @clang_doxygen_generate_qhp@
+
+# If the QHG_LOCATION tag is specified, the QCH_FILE tag can 
+# be used to specify the file name of the resulting .qch file. 
+# The path specified is relative to the HTML output folder.
+
+QCH_FILE               = @clang_doxygen_qch_filename@
+
+# The QHP_NAMESPACE tag specifies the namespace to use when generating 
+# Qt Help Project output. For more information please see 
+# http://qt-project.org/doc/qt-4.8/qthelpproject.html#namespace
+
+QHP_NAMESPACE          = @clang_doxygen_qhp_namespace@
+
+# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating 
+# Qt Help Project output. For more information please see 
+# http://qt-project.org/doc/qt-4.8/qthelpproject.html#virtual-folders
+
+QHP_VIRTUAL_FOLDER     = doc
+
+# If QHP_CUST_FILTER_NAME is set, it specifies the name of a custom filter to 
+# add. For more information please see 
+# http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters
+
+QHP_CUST_FILTER_NAME   = @clang_doxygen_qhp_cust_filter_name@
+
+# The QHP_CUST_FILT_ATTRS tag specifies the list of the attributes of the 
+# custom filter to add. For more information please see 
+# <a href="http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters"> 
+# Qt Help Project / Custom Filters</a>.
+
+QHP_CUST_FILTER_ATTRS  = @clang_doxygen_qhp_cust_filter_attrs@
+
+# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this 
+# project's 
+# filter section matches. 
+# <a href="http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes"> 
+# Qt Help Project / Filter Attributes</a>.
+
+QHP_SECT_FILTER_ATTRS  = 
+
+# If the GENERATE_QHP tag is set to YES, the QHG_LOCATION tag can 
+# be used to specify the location of Qt's qhelpgenerator. 
+# If non-empty doxygen will try to run qhelpgenerator on the generated 
+# .qhp file.
+
+QHG_LOCATION           = @clang_doxygen_qhelpgenerator_path@
+
 # The DISABLE_INDEX tag can be used to turn on/off the condensed index at 
 # top of each HTML page. The value NO (the default) enables the index and 
 # the value YES disables it.
 
 DISABLE_INDEX          = NO
 
 # This tag can be used to set the number of enum values (range [1..20]) 
 # that doxygen will group on one line in the generated HTML documentation.
 
 ENUM_VALUES_PER_LINE   = 4
 
 # If the GENERATE_TREEVIEW tag is set to YES, a side panel will be
 # generated containing a tree-like index structure (just like the one that 
 # is generated for HTML Help). For this to work a browser that supports 
 # JavaScript, DHTML, CSS and frames is required (for instance Mozilla 1.0+, 
 # Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are 
 # probably better off using the HTML help feature.