Skip to content

Commit 700a991

Browse files
committedMar 7, 2014
[docs] Teach CMake docs build how to generate Qt Creator help/documentation files.
Patch by Konrad Kleine. Differential Revision: http://llvm-reviews.chandlerc.com/D2967 llvm-svn: 203272
1 parent c5a3c9f commit 700a991

File tree

3 files changed

+115
-31
lines changed

3 files changed

+115
-31
lines changed
 

‎llvm/docs/CMake.rst

+44
Original file line numberDiff line numberDiff line change
@@ -283,6 +283,50 @@ LLVM-specific variables
283283
are ``Address``, ``Memory`` and ``MemoryWithOrigins``. Defaults to empty
284284
string.
285285

286+
**LLVM_ENABLE_DOXYGEN**:BOOL
287+
Enables the generation of browsable HTML documentation using doxygen.
288+
Defaults to OFF.
289+
290+
**LLVM_ENABLE_DOXYGEN_QT_HELP**:BOOL
291+
Enables the generation of a Qt Compressed Help file. Defaults to OFF.
292+
This affects the make target ``doxygen-llvm``. When enabled, apart from
293+
the normal HTML output generated by doxygen, this will produce a QCH file
294+
named ``org.llvm.qch``. You can then load this file into Qt Creator.
295+
This option is only useful in combination with ``-DLLVM_ENABLE_DOXYGEN=ON``;
296+
otherwise this has no effect.
297+
298+
**LLVM_DOXYGEN_QCH_FILENAME**:STRING
299+
The filename of the Qt Compressed Help file that will be genrated when
300+
``-DLLVM_ENABLE_DOXYGEN=ON`` and
301+
``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON`` are given. Defaults to
302+
``org.llvm.qch``.
303+
This option is only useful in combination with
304+
``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;
305+
otherwise this has no effect.
306+
307+
**LLVM_DOXYGEN_QHP_NAMESPACE**:STRING
308+
Namespace under which the intermediate Qt Help Project file lives. See `Qt
309+
Help Project <http://qt-project.org/doc/qt-4.8/qthelpproject.html#namespace>`_
310+
for more information. Defaults to "org.llvm". This option is only useful in
311+
combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise
312+
this has no effect.
313+
314+
**LLVM_DOXYGEN_QHP_CUST_FILTER_NAME**:STRING
315+
See `Qt Help Project
316+
<http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters>`_ for
317+
more information. Defaults to the CMake variable ``${PACKAGE_STRING}`` which
318+
is a combination of the package name and version string. This filter can then
319+
be used in Qt Creator to select only documentation from LLVM when browsing
320+
through all the help files that you might have loaded. This option is only
321+
useful in combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;
322+
otherwise this has no effect.
323+
324+
**LLVM_DOXYGEN_QHELPGENERATOR_PATH**:STRING
325+
The path to the ``qhelpgenerator`` executable. Defaults to whatever CMake's
326+
``find_program()`` can find. This option is only useful in combination with
327+
``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise this has no
328+
effect.
329+
286330
Executing the test suite
287331
========================
288332

‎llvm/docs/CMakeLists.txt

+40
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,40 @@ if (LLVM_ENABLE_DOXYGEN)
2222
set(extra_search_mappings "")
2323
endif()
2424

25+
# If asked, configure doxygen for the creation of a Qt Compressed Help file.
26+
option(LLVM_ENABLE_DOXYGEN_QT_HELP
27+
"Generate a Qt Compressed Help file." OFF)
28+
if (LLVM_ENABLE_DOXYGEN_QT_HELP)
29+
set(LLVM_DOXYGEN_QCH_FILENAME "org.llvm.qch" CACHE STRING
30+
"Filename of the Qt Compressed help file")
31+
set(LLVM_DOXYGEN_QHP_NAMESPACE "org.llvm" CACHE STRING
32+
"Namespace under which the intermediate Qt Help Project file lives")
33+
set(LLVM_DOXYGEN_QHP_CUST_FILTER_NAME "${PACKAGE_STRING}" CACHE STRING
34+
"See http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters")
35+
set(LLVM_DOXYGEN_QHP_CUST_FILTER_ATTRS "${PACKAGE_NAME},${PACKAGE_VERSION}" CACHE STRING
36+
"See http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes")
37+
find_program(LLVM_DOXYGEN_QHELPGENERATOR_PATH qhelpgenerator
38+
DOC "Path to the qhelpgenerator binary")
39+
if (NOT LLVM_DOXYGEN_QHELPGENERATOR_PATH)
40+
message(FATAL_ERROR "Failed to find qhelpgenerator binary")
41+
endif()
42+
43+
set(llvm_doxygen_generate_qhp "YES")
44+
set(llvm_doxygen_qch_filename "${LLVM_DOXYGEN_QCH_FILENAME}")
45+
set(llvm_doxygen_qhp_namespace "${LLVM_DOXYGEN_QHP_NAMESPACE}")
46+
set(llvm_doxygen_qhelpgenerator_path "${LLVM_DOXYGEN_QHELPGENERATOR_PATH}")
47+
set(llvm_doxygen_qhp_cust_filter_name "${LLVM_DOXYGEN_QHP_CUST_FILTER_NAME}")
48+
set(llvm_doxygen_qhp_cust_filter_attrs "${LLVM_DOXYGEN_QHP_CUST_FILTER_ATTRS}")
49+
50+
else()
51+
set(llvm_doxygen_generate_qhp "NO")
52+
set(llvm_doxygen_qch_filename "")
53+
set(llvm_doxygen_qhp_namespace "")
54+
set(llvm_doxygen_qhelpgenerator_path "")
55+
set(llvm_doxygen_qhp_cust_filter_name "")
56+
set(llvm_doxygen_qhp_cust_filter_attrs "")
57+
endif()
58+
2559
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doxygen.cfg.in
2660
${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg @ONLY)
2761

@@ -33,6 +67,12 @@ if (LLVM_ENABLE_DOXYGEN)
3367
set(enable_server_based_search)
3468
set(enable_external_search)
3569
set(extra_search_mappings)
70+
set(llvm_doxygen_generate_qhp)
71+
set(llvm_doxygen_qch_filename)
72+
set(llvm_doxygen_qhp_namespace)
73+
set(llvm_doxygen_qhelpgenerator_path)
74+
set(llvm_doxygen_qhp_cust_filter_name)
75+
set(llvm_doxygen_qhp_cust_filter_attrs)
3676

3777
add_custom_target(doxygen-llvm
3878
COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg

‎llvm/docs/doxygen.cfg.in

+31-31
Original file line numberDiff line numberDiff line change
@@ -938,58 +938,58 @@ BINARY_TOC = NO
938938

939939
TOC_EXPAND = NO
940940

941-
# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and
942-
# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated
943-
# that can be used as input for Qt's qhelpgenerator to generate a
941+
# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and
942+
# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated
943+
# that can be used as input for Qt's qhelpgenerator to generate a
944944
# Qt Compressed Help (.qch) of the generated HTML documentation.
945945

946-
GENERATE_QHP = NO
946+
GENERATE_QHP = @llvm_doxygen_generate_qhp@
947947

948-
# If the QHG_LOCATION tag is specified, the QCH_FILE tag can
949-
# be used to specify the file name of the resulting .qch file.
948+
# If the QHG_LOCATION tag is specified, the QCH_FILE tag can
949+
# be used to specify the file name of the resulting .qch file.
950950
# The path specified is relative to the HTML output folder.
951951

952-
QCH_FILE =
952+
QCH_FILE = @llvm_doxygen_qch_filename@
953953

954-
# The QHP_NAMESPACE tag specifies the namespace to use when generating
955-
# Qt Help Project output. For more information please see
956-
# http://doc.trolltech.com/qthelpproject.html#namespace
954+
# The QHP_NAMESPACE tag specifies the namespace to use when generating
955+
# Qt Help Project output. For more information please see
956+
# http://qt-project.org/doc/qt-4.8/qthelpproject.html#namespace
957957

958-
QHP_NAMESPACE = org.doxygen.Project
958+
QHP_NAMESPACE = @llvm_doxygen_qhp_namespace@
959959

960-
# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating
961-
# Qt Help Project output. For more information please see
962-
# http://doc.trolltech.com/qthelpproject.html#virtual-folders
960+
# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating
961+
# Qt Help Project output. For more information please see
962+
# http://qt-project.org/doc/qt-4.8/qthelpproject.html#virtual-folders
963963

964964
QHP_VIRTUAL_FOLDER = doc
965965

966-
# If QHP_CUST_FILTER_NAME is set, it specifies the name of a custom filter to
967-
# add. For more information please see
968-
# http://doc.trolltech.com/qthelpproject.html#custom-filters
966+
# If QHP_CUST_FILTER_NAME is set, it specifies the name of a custom filter to
967+
# add. For more information please see
968+
# http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters
969969

970-
QHP_CUST_FILTER_NAME =
970+
QHP_CUST_FILTER_NAME = @llvm_doxygen_qhp_cust_filter_name@
971971

972-
# The QHP_CUST_FILT_ATTRS tag specifies the list of the attributes of the
973-
# custom filter to add. For more information please see
974-
# <a href="http://doc.trolltech.com/qthelpproject.html#custom-filters">
972+
# The QHP_CUST_FILT_ATTRS tag specifies the list of the attributes of the
973+
# custom filter to add. For more information please see
974+
# <a href="http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters">
975975
# Qt Help Project / Custom Filters</a>.
976976

977-
QHP_CUST_FILTER_ATTRS =
977+
QHP_CUST_FILTER_ATTRS = @llvm_doxygen_qhp_cust_filter_attrs@
978978

979-
# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this
980-
# project's
981-
# filter section matches.
982-
# <a href="http://doc.trolltech.com/qthelpproject.html#filter-attributes">
979+
# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this
980+
# project's
981+
# filter section matches.
982+
# <a href="http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes">
983983
# Qt Help Project / Filter Attributes</a>.
984984

985-
QHP_SECT_FILTER_ATTRS =
985+
QHP_SECT_FILTER_ATTRS =
986986

987-
# If the GENERATE_QHP tag is set to YES, the QHG_LOCATION tag can
988-
# be used to specify the location of Qt's qhelpgenerator.
989-
# If non-empty doxygen will try to run qhelpgenerator on the generated
987+
# If the GENERATE_QHP tag is set to YES, the QHG_LOCATION tag can
988+
# be used to specify the location of Qt's qhelpgenerator.
989+
# If non-empty doxygen will try to run qhelpgenerator on the generated
990990
# .qhp file.
991991

992-
QHG_LOCATION =
992+
QHG_LOCATION = @llvm_doxygen_qhelpgenerator_path@
993993

994994
# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files
995995
# will be generated, which together with the HTML files, form an Eclipse help

0 commit comments

Comments
 (0)
Please sign in to comment.