[PATCH] Qt Creator help/documentation file for LLVM
Konrad Wilhelm Kleine
konrad.wilhelm.kleine at gmail.com
Wed Mar 5 08:19:31 PST 2014
Hi gottesmm, gribozavr, klimek,
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_DOXYGEN_GENERATE_QT_COMPRESSED_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 print 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. 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
http://llvm-reviews.chandlerc.com/D2967
Files:
docs/CMake.rst
docs/CMakeLists.txt
docs/doxygen.cfg.in
Index: docs/CMake.rst
===================================================================
--- docs/CMake.rst
+++ docs/CMake.rst
@@ -283,6 +283,50 @@
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
========================
Index: docs/CMakeLists.txt
===================================================================
--- docs/CMakeLists.txt
+++ docs/CMakeLists.txt
@@ -22,6 +22,38 @@
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)
Index: docs/doxygen.cfg.in
===================================================================
--- docs/doxygen.cfg.in
+++ docs/doxygen.cfg.in
@@ -938,58 +938,58 @@
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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: D2967.1.patch
Type: text/x-patch
Size: 8847 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20140305/c5d142c7/attachment.bin>
More information about the llvm-commits
mailing list