Doxygen: add build option to use svg instead of png files for graphs

[hans]

Summary

The doxygen output is currently not practical for shipping with releases, as it weighs in at about 1 GB when xz-compressed.

If we'd use svg instead of png for the diagrams, the output compresses to about 65 MB :-)

[hans]

Ping?

I think this is a really straight-forward patch, but it would be great to have someone take a look at it.

[hans]

Logan doesn't seem to be around. Takumi or Sean, maybe you can take a look?

[silvas]

This looks fine.

Just for reference, is the significantly decreased size due to the SVG files just being smaller, or compressing better? Given that most browsers seem to support SVG nowadays (http://caniuse.com/#feat=svg), it might make sense to just hardcode svg in the doxygen.cfg.in file (with a comment explaining the choice). That avoids surfacing any complexity in cmake.

[silvas]

Forgot to hit accept.

[hans]

In D11994#226133, @silvas wrote:

Just for reference, is the significantly decreased size due to the SVG files just being smaller, or compressing better? Given that most browsers seem to support SVG nowadays (http://caniuse.com/#feat=svg), it might make sense to just hardcode svg in the doxygen.cfg.in file (with a comment explaining the choice). That avoids surfacing any complexity in cmake.

The svg files are smaller, but the big reduction comes from better compression.

For LLVM, the doxygen with png is 1.6 GB uncompressed and 980 MB compressed. With svg, it's 867 MB uncompressed and 65 MB compressed.

[llvm-commits]

• msg-10558-162.txt162 BDownload

docs/CMake.rst

 .. _Qt Help Project: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters
 
 **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
   ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise this has no
   effect.
 
+**LLVM_DOXYGEN_SVG**:BOOL
+  Uses .svg files instead of .png files for graphs in the Doxygen output.
+  Defaults to OFF.
+
 **LLVM_ENABLE_SPHINX**:BOOL
   If enabled CMake will search for the ``sphinx-build`` executable and will make
   the ``SPHINX_OUTPUT_HTML`` and ``SPHINX_OUTPUT_MAN`` CMake options available.
   Defaults to OFF.
 
 **SPHINX_EXECUTABLE**:STRING
   The path to the ``sphinx-build`` executable detected by CMake.
 

docs/CMakeLists.txt

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()
   
+  option(LLVM_DOXYGEN_SVG
+    "Use svg instead of png files for doxygen graphs." OFF)
+  if (LLVM_DOXYGEN_SVG)
+    set(DOT_IMAGE_FORMAT "svg")
+  else()
+    set(DOT_IMAGE_FORMAT "png")
+  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(llvm_doxygen_generate_qhp)
   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)
+  set(DOT_IMAGE_FORMAT)
 
   add_custom_target(doxygen-llvm
     COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg
     WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
     COMMENT "Generating llvm doxygen documentation." VERBATIM)
 
   if (LLVM_BUILD_DOCS)
     add_dependencies(doxygen doxygen-llvm)

docs/Makefile

cat $< | sed \
     -e 's/@extra_search_mappings@//g' \
     -e 's/@llvm_doxygen_generate_qhp@//g' \
     -e 's/@llvm_doxygen_qch_filename@//g' \
     -e 's/@llvm_doxygen_qhelpgenerator_path@//g' \
     -e 's/@llvm_doxygen_qhp_cust_filter_attrs@//g' \
     -e 's/@llvm_doxygen_qhp_cust_filter_name@//g' \
     -e 's/@llvm_doxygen_qhp_namespace@//g' \
     -e 's/@searchengine_url@//g' \
+    -e 's/@DOT_IMAGE_FORMAT@/png/g' \
     > $@
 endif
 
 include $(LEVEL)/Makefile.common
 
 HTML       := $(wildcard $(PROJ_SRC_DIR)/*.html) \
               $(wildcard $(PROJ_SRC_DIR)/*.css)
 DOXYFILES  := doxygen.cfg.in doxygen.intro

docs/doxygen.cfg.in

 # generated by dot.
 # Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order
 # to make the SVG files visible in IE 9+ (other browsers do not have this
 # requirement).
 # Possible values are: png, jpg, gif and svg.
 # The default value is: png.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_IMAGE_FORMAT       = png
+DOT_IMAGE_FORMAT       = @DOT_IMAGE_FORMAT@
 
 # If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to
 # enable generation of interactive SVG images that allow zooming and panning.
 #
 # Note that this requires a modern browser other than Internet Explorer. Tested
 # and working are Firefox, Chrome, Safari, and Opera.
 # Note: For IE 9+ you need to set HTML_FILE_EXTENSION to xhtml in order to make
 # the SVG files visible. Older versions of IE do not have SVG support.