Qt Creator help/documentation file for LLVM

[kwk]

Summary

I saw that the LLVM documentation at http://llvm.org/doxygen/ is generated by doxygen. This is very cool because with just a few additional settings one could get a Qt Compressed Help (QCH) file. After applying my patch, you can configure LLVM using CMake with these defines (the generator isn't really important):

cmake -G Ninja ../llvm \
-DLLVM_ENABLE_DOXYGEN=ON \
-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON

Prerequisites

You need to have the "qhelpgenerator" binary installed for this to work. On my system this is provided by these packages:

qt4-dev-tools
qttools5-dev-tools

Other QCH configuration variables

There are more CMake configurations you can specify, please see the docs/CMake.rst for documentation on them.

Note, that the default behaviour for generating the documentation for LLVM is not changed by my commit.

Building the Qt compressed help file

Then build the doxygen documentation as well as the QCH file:

ninja doxygen-llvm

This will build the generation of the a file called "org.llvm.qch". This QCH file can then be used in Qt Creator for direct documentation lookup of LLVM symbols. It will be located in your build directory under

docs/doxygen/html/org.llvm.qch

After importing this into the help system of Qt Creator you can hover your cursor over a symbol like llvm::APFloat and press <F1>, this will instantly bring up the documentation for this class in a documentation pane to the right of your editing window.

The downside of this documentation file is that it is really big in size, since it basically contains all of the HTML files generated by doxygen. But for a single developer's machine, this is okay, I guess.

Troubleshooting

If you you don't find "org.llvm.qch" after building the documentation, chances are that you ran into a known problem with doxgen. To circumvent it, navigate to docs/doxygen/html in your your build directory.

There's an intermediate Qt Help Project file called "index.qhp" which most likely contains a broken XML code. To fix this, run this command manually

qhelpgenerator -o org.llvm.qch index.qhp

If it prints something like this:

Error in line 97929: Opening and ending tag mismatch.

Open the file at the given position and simply remove the </section> tag infront of the </toc> tag. Then rerun qhelpgenerator -o org.llvm.qch index.qhp. It should print something like this:

Building up file structure...
Insert custom filters...
Insert help data for filter section (1 of 1)...
Insert files...
Insert contents...
Insert indices...
Documentation successfully generated.

By now you should have your Qt Compressed Help file!

Other projects having Qt Compressed Help files

This website lists Qt Compressed Help files for other projects:

http://qt-project.org/wiki/Qt_Creator_Documentation_Gallery

I hope that somebody finds this patch useful.

Regards,
Konrad

[kwk]

Here, how the Qt Compressed Help file looks like when loaded into Qt Creator:

{F46670}

[gribozavr]

This patch LGTM, but please wait for another review from someone who is more familiar with our build system.

[gottesmm]

Please see the comments above.

docs/CMake.rst

290

Make sure to update this with respect to my comments below.

docs/CMakeLists.txt

26

I don't think we are doing banner comments in CMake. Double check there is precedent for this. If there is ok, but if not just get rid of the banner. Something like this would be good:

1. If asked, configure doxygen for the creation of a Qt Compressed Help file.

28

Could you change this variable name to LLVM_ENABLE_DOXYGEN_QT_HELP.

39

You should check if we successfully find the program and error via message(FATAL_ERROR ...). If they asked us to generate this and we can't find the program it seems to me that that should be a hard error.

60

You should undefine the cmake variables you are defining for use in doxygen here like the rest of the cmake variables used to configure the doxygen file.

[gottesmm]

Had a phabricator formatting issue. Its fixed now.

docs/CMakeLists.txt

26

phabricator turned my # into a 1 since it thought that it was a list. That should be:

"# If asked, configure doxygen for the creation of a Qt Compressed Help file."

[gottesmm]

Please make the requested changes. (I should have not sent them as comments. I am not that familiar with phabricator so I made the mistake = /).

[kwk]

Qt Creator help/documentation file for LLVM (update)

I've incorporated the changes requested by gottesmm. These include:

• Removed banner comment in docs/CMakeLists.txt file
• Renamed LLVM_DOXYGEN_GENERATE_QT_COMPRESSED_HELP to LLVM_ENABLE_DOXYGEN_QT_HELP
• Updated docs/CMake.rst description of build parameters
• Issue a FATAL_ERROR message during CMake configuration when qhelpgenerator binary wasn't found
• Undefine CMake variables that are no longer used once the doxygen.cfg.in file was configured.

[kwk]

gottesmm, do you accept my changes and if so can you commit them?

[gottesmm]

Small nit, but I will just fix it and commit it.

docs/CMakeLists.txt

39

One last nit. In general in LLVM we prefer to do this sort of thing like this:

if (NOT LLVM_DOXYGEN_QHELPGENERATOR_PATH)

message(FATAL_ERROR "Failed to find qhelpgenerator binary")

endif()

set(llvm_doxygen_generate_qhp "YES")
set(llvm_doxygen_qch_filename "${LLVM_DOXYGEN_QCH_FILENAME}")
set(llvm_doxygen_qhp_namespace "${LLVM_DOXYGEN_QHP_NAMESPACE}")
set(llvm_doxygen_qhelpgenerator_path "${LLVM_DOXYGEN_QHELPGENERATOR_PATH}")
set(llvm_doxygen_qhp_cust_filter_name "${LLVM_DOXYGEN_QHP_CUST_FILTER_NAME}")
set(llvm_doxygen_qhp_cust_filter_attrs "${LLVM_DOXYGEN_QHP_CUST_FILTER_ATTRS}")

But I will just fix it since it is such a nit.

[gottesmm]

r203272

[kwk]

Closed by commit rL203272 (authored by mgottesman).

docs/CMake.rst

**LLVM_ENABLE_ZLIB**:BOOL
   Build with zlib to support compression/uncompression in LLVM tools.
   Defaults to ON.
 
 **LLVM_USE_SANITIZER**:STRING
   Define the sanitizer used to build LLVM binaries and tests. Possible values
   are ``Address``, ``Memory`` and ``MemoryWithOrigins``. Defaults to empty
   string.
 
+**LLVM_ENABLE_DOXYGEN**:BOOL
+  Enables the generation of browsable HTML documentation using doxygen.
+  Defaults to OFF.
+
+**LLVM_DOXYGEN_GENERATE_QT_COMPRESSED_HELP**:BOOL
+  Enables the generation of a Qt Compressed Help file. Defaults to OFF.
+  This affects the make target ``doxygen-llvm``. When enabled, apart from
+  the normal HTML output generated by doxygen, this will produce a QCH file
+  named ``org.llvm.qch``. You can then load this file into Qt Creator.
+  This option is only useful in combination with ``-DLLVM_ENABLE_DOXYGEN=ON``;
+  otherwise this has no effect.
+
+**LLVM_DOXYGEN_QCH_FILENAME**:STRING
+  The filename of the Qt Compressed Help file that will be genrated when
+  ``-DLLVM_ENABLE_DOXYGEN=ON`` and 
+  ``-LLVM_DOXYGEN_GENERATE_QT_COMPRESSED_HELP=ON`` are given. Defaults to
+  ``org.llvm.qch``.
+  This option is only useful in combination with
+  ``-LLVM_DOXYGEN_GENERATE_QT_COMPRESSED_HELP=ON``;
+  otherwise this has no effect.
+
+**LLVM_DOXYGEN_QHP_NAMESPACE**:STRING
+  Namespace under which the intermediate Qt Help Project file lives. See `Qt
+  Help Project <http://qt-project.org/doc/qt-4.8/qthelpproject.html#namespace>`_
+  for more information. Defaults to "org.llvm". This option is only useful in
+  combination with ``-LLVM_DOXYGEN_GENERATE_QT_COMPRESSED_HELP=ON``; otherwise
+  this has no effect.
+    
+**LLVM_DOXYGEN_QHP_CUST_FILTER_NAME**:STRING
+  See `Qt Help Project
+  <http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters>`_ for
+  more information. Defaults to the CMake variable ``${PACKAGE_STRING}`` which
+  is a combination of the package name and version string. This filter can then
+  be used in Qt Creator to select only documentation from LLVM when browsing
+  through all the help files that you might have loaded. This option is only
+  useful in combination with ``-LLVM_DOXYGEN_GENERATE_QT_COMPRESSED_HELP=ON``;
+  otherwise this has no effect.
+
+**LLVM_DOXYGEN_QHELPGENERATOR_PATH**:STRING
+  The path to the ``qhelpgenerator`` executable. Defaults to whatever CMake's
+  ``find_program()`` can find. This option is only useful in combination with
+  ``-LLVM_DOXYGEN_GENERATE_QT_COMPRESSED_HELP=ON``; otherwise this has no
+  effect.
+
 Executing the test suite
 ========================
 
 Testing is performed when the *check* target is built. For instance, if you are
 using makefiles, execute this command while on the top level of your build
 directory:
 
 .. code-block:: console

docs/CMakeLists.txt

if (LLVM_ENABLE_DOXYGEN)
   else()
     set(enable_searchengine "NO")
     set(searchengine_url "")
     set(enable_server_based_search "NO")
     set(enable_external_search "NO")
     set(extra_search_mappings "")
   endif()
   
+  #-----------------------------------------------
+  # This lets you create a Qt Compressed Help file
+  #-----------------------------------------------
+  option(LLVM_DOXYGEN_GENERATE_QT_COMPRESSED_HELP 
+    "Generate a Qt Compressed Help file." OFF)
+  if (LLVM_DOXYGEN_GENERATE_QT_COMPRESSED_HELP)
+    set(LLVM_DOXYGEN_QCH_FILENAME "org.llvm.qch" CACHE STRING
+      "Filename of the Qt Compressed help file")
+    set(LLVM_DOXYGEN_QHP_NAMESPACE "org.llvm" CACHE STRING 
+      "Namespace under which the intermediate Qt Help Project file lives")
+    set(LLVM_DOXYGEN_QHP_CUST_FILTER_NAME "${PACKAGE_STRING}" CACHE STRING
+      "See http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters")
+    set(LLVM_DOXYGEN_QHP_CUST_FILTER_ATTRS "${PACKAGE_NAME},${PACKAGE_VERSION}" CACHE STRING
+      "See http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes")
+    find_program(LLVM_DOXYGEN_QHELPGENERATOR_PATH qhelpgenerator 
+      DOC "Path to the qhelpgenerator binary")
+    
+    set(llvm_doxygen_generate_qhp "YES")
+    set(llvm_doxygen_qch_filename "${LLVM_DOXYGEN_QCH_FILENAME}")
+    set(llvm_doxygen_qhp_namespace "${LLVM_DOXYGEN_QHP_NAMESPACE}")
+    set(llvm_doxygen_qhelpgenerator_path "${LLVM_DOXYGEN_QHELPGENERATOR_PATH}")
+    set(llvm_doxygen_qhp_cust_filter_name "${LLVM_DOXYGEN_QHP_CUST_FILTER_NAME}")
+    set(llvm_doxygen_qhp_cust_filter_attrs "${LLVM_DOXYGEN_QHP_CUST_FILTER_ATTRS}")
+  else()
+    set(llvm_doxygen_generate_qhp "NO")
+    set(llvm_doxygen_qch_filename "")
+    set(llvm_doxygen_qhp_namespace "")
+    set(llvm_doxygen_qhelpgenerator_path "")
+    set(llvm_doxygen_qhp_cust_filter_name "")
+    set(llvm_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)
 

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
+# 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           = NO
+GENERATE_QHP           = @llvm_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.
+# 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               =
+QCH_FILE               = @llvm_doxygen_qch_filename@
 
-# The QHP_NAMESPACE tag specifies the namespace to use when generating
-# Qt Help Project output. For more information please see
-# http://doc.trolltech.com/qthelpproject.html#namespace
+# 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          = org.doxygen.Project
+QHP_NAMESPACE          = @llvm_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://doc.trolltech.com/qthelpproject.html#virtual-folders
+# 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://doc.trolltech.com/qthelpproject.html#custom-filters
+# 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   =
+QHP_CUST_FILTER_NAME   = @llvm_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://doc.trolltech.com/qthelpproject.html#custom-filters">
+# 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  =
+QHP_CUST_FILTER_ATTRS  = @llvm_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://doc.trolltech.com/qthelpproject.html#filter-attributes">
+# 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  =
+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
+# 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           =
+QHG_LOCATION           = @llvm_doxygen_qhelpgenerator_path@
 
 # If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files
 #  will be generated, which together with the HTML files, form an Eclipse help
 # plugin. To install this plugin and make it available under the help contents
 # menu in Eclipse, the contents of the directory containing the HTML and XML
 # files needs to be copied into the plugins directory of eclipse. The name of
 # the directory within the plugins directory should be the same as
 # the ECLIPSE_DOC_ID value. After copying Eclipse needs to be restarted before