cmake: Support overriding Sphinx HTML doc install directory

[mgorny]

Summary

Provide ${PROJECT}_INSTALL_SPHINX_HTML_DIR variables (e.g. LLVM_INSTALL_SPHINX_HTML_DIR) to override Sphinx HTML doc install directory.

Bug: https://llvm.org/bugs/show_bug.cgi?id=23780

[delcypher]

I agree with what you're trying achieve but I have a few nits. Once we've fixed those you also need to document the option in doc/CMake.rst (under LLVM-specific variables). You probably only need to document for LLVM (i.e. LLVM_INSTALL_SPHINX_HTML_DIR or whatever we decide to name it) and not the other sub-projects.

If you can get all that done and @rnk has no objections we can probably merge.

cmake/modules/AddSphinxTarget.cmake

57

This is not a good name for the variable because we also generate HTML doxygen documentation and thus this variable name is ambiguous (see https://github.com/llvm-mirror/llvm/blob/2c37c7740e3ea7a68447b4890e062abca9b69c0f/docs/CMakeLists.txt#L97 ). How about

${project_upper}_INSTALL_SPHINX_HTML_DIR

?

60

Why did you change "${SPHINX_BUILD_DIR}" to "${SPHINX_BUILD_DIR}/." ?

[mgorny]

Thanks for the review. I've replied to your comments, and will update the patch in a few hours.

cmake/modules/AddSphinxTarget.cmake

57

You're right, I'll use that. I'm planning to also add variables for the other kinds of documentation in a separate patch (since they end up in /usr/docs...).

60

This is necessary to avoid implicitly creating additional 'html' subdirectory, i.e. otherwise it would be installed as ${...}/html.

[mgorny]

Updated the variable name and added to docs.

[delcypher]

cmake/modules/AddSphinxTarget.cmake

60

I see. There should be a comment explaining this then.

docs/CMake.rst

461

This default is incorrect. The default is actually share/doc/llvm/html. It does not contain the CMAKE_INSTALL_PREFIX.

Your text probably ought to say something like:

The path to install Sphinx-generated HTML documentation to. This path relative to the CMAKE_INSTALL_PREFIX and by default
is `share/doc/llvm/html`.

[mgorny]

docs/CMake.rst

461

Well, this is not 100% correct since it is relative only when it's not absolute ;-). I'll try to find a good way to express it.

[mgorny]

Added the comment and updated the doc. Hope it's clear enough now.

[delcypher]

Thanks for making the changes. LGTM.

[mgorny]

Thanks a lot for the review.

cmake/modules/AddSphinxTarget.cmake

if (LLVM_BUILD_DOCS)
     # Handle installation
     if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY)
       if (builder STREQUAL man)
         # FIXME: We might not ship all the tools that these man pages describe
         install(DIRECTORY "${SPHINX_BUILD_DIR}/" # Slash indicates contents of
                 DESTINATION share/man/man1)
 
       elseif (builder STREQUAL html)
-        install(DIRECTORY "${SPHINX_BUILD_DIR}"
-                DESTINATION "share/doc/${project}")
+        string(TOUPPER "${project}" project_upper)
+        set(${project_upper}_INSTALL_SPHINX_HTML_DIR "share/doc/${project}/html"
+            CACHE STRING "HTML documentation install directory for ${project}")
+
+        # '/.' indicates: copy the contents of the directory directly into
+        # the specified destination, without recreating the last component
+        # of ${SPHINX_BUILD_DIR} implicitly.
+        install(DIRECTORY "${SPHINX_BUILD_DIR}/."
+                DESTINATION "${${project_upper}_INSTALL_SPHINX_HTML_DIR}")
       else()
         message(WARNING Installation of ${builder} not supported)
       endif()
     endif()
   endif()
 endfunction()

docs/CMake.rst

**SPHINX_OUTPUT_MAN**:BOOL
   the man pages are added (but not built by default unless ``LLVM_BUILD_DOCS``
   is enabled). Currently the only target added is ``docs-llvm-man``. Defaults
   to ON.
 
 **SPHINX_WARNINGS_AS_ERRORS**:BOOL
   If enabled then sphinx documentation warnings will be treated as
   errors. Defaults to ON.
 
+**LLVM_INSTALL_SPHINX_HTML_DIR**:STRING
+  The path to install Sphinx-generated HTML documentation to. This path can
+  either be absolute or relative to the CMAKE_INSTALL_PREFIX. Defaults to
+  `share/doc/llvm/html`.
+
 **LLVM_CREATE_XCODE_TOOLCHAIN**:BOOL
   OS X Only: If enabled CMake will generate a target named
   'install-xcode-toolchain'. This target will create a directory at
   $CMAKE_INSTALL_PREFIX/Toolchains containing an xctoolchain directory which can
   be used to override the default system tools. 
 
 **LLVM_BUILD_LLVM_DYLIB**:BOOL
   If enabled, the target for building the libLLVM shared library is added.