This is an archive of the discontinued LLVM Phabricator instance.

Qt Creator help/documentation file for LLVM
ClosedPublic

Authored by kwk on Mar 5 2014, 8:19 AM.

Details

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

Diff Detail

Event Timeline

kwk added a comment.Mar 5 2014, 8:20 AM

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

{F46670}

gribozavr accepted this revision.Mar 5 2014, 9:08 AM

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

Please see the comments above.

docs/CMake.rst
290 ↗(On Diff #7556)

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

docs/CMakeLists.txt
26 ↗(On Diff #7556)

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 ↗(On Diff #7556)

Could you change this variable name to LLVM_ENABLE_DOXYGEN_QT_HELP.

39 ↗(On Diff #7556)

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 ↗(On Diff #7556)

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.

Had a phabricator formatting issue. Its fixed now.

docs/CMakeLists.txt
26 ↗(On Diff #7556)

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 requested changes to this revision.Mar 5 2014, 10:30 AM

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 updated this revision to Unknown Object (????).Mar 6 2014, 12:18 AM

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 added a comment.Mar 7 2014, 3:12 AM

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

gottesmm accepted this revision.Mar 7 2014, 11:18 AM

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

docs/CMakeLists.txt
39 ↗(On Diff #7583)

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 closed this revision.Mar 7 2014, 11:26 AM

r203272

kwk closed this revision.Mar 7 2014, 11:26 AM

Closed by commit rL203272 (authored by mgottesman).