[Docs] Make it possible to generate the python reference without building all of LLDB

[JDevlieghere]

Summary

As discussed on the mailing list, we should be able to generate the Python reference without building all of LLDB. To make that possible I create a dummy python package, which is then parsed by epydoc. The latter will complain that it couldn't import lldb, but that doesn't matter as far as generation of the docs is concerned.

[labath]

Looks good to me. Thanks for looking into this.

On one hand, it would be nice to create avoid creating the fake package, and just run epydoc from the final destination, but on the other, the nice thing about this is that it will always run in the same environment and not depend on whether you happen to have _lldb.so built or not (plus, with all the complexity around frameworks and stuff, it might be hard to get __init__.py to be placed in the final destination without depending on any of the other build steps).

lldb/CMakeLists.txt

 if(APPLE)
   add_definitions(-DLLDB_USE_OS_LOG)
 endif()
 
 if (WIN32)
   add_definitions(-D_ENABLE_EXTENDED_ALIGNED_STORAGE)
 endif()
 
-add_subdirectory(docs)
 if (NOT LLDB_DISABLE_PYTHON)
   add_subdirectory(scripts)
 endif ()
 add_subdirectory(source)
 add_subdirectory(tools)
+add_subdirectory(docs)
 
 option(LLDB_INCLUDE_TESTS "Generate build targets for the LLDB unit tests." ${LLVM_INCLUDE_TESTS})
 option(LLDB_TEST_USE_CUSTOM_C_COMPILER "Use the C compiler provided via LLDB_TEST_C_COMPILER for building test inferiors (instead of the just-built compiler). Defaults to OFF." OFF)
 option(LLDB_TEST_USE_CUSTOM_CXX_COMPILER "Use the C++ compiler provided via LLDB_TEST_CXX_COMPILER for building test inferiors (instead of the just-built compiler). Defaults to OFF." OFF)
 if(LLDB_INCLUDE_TESTS)
 
   # Set the path to the default lldb test executable.
   set(LLDB_DEFAULT_TEST_EXECUTABLE "${LLVM_RUNTIME_OUTPUT_INTDIR}/lldb${CMAKE_EXECUTABLE_SUFFIX}")

lldb/docs/CMakeLists.txt

 include(FindDoxygen)
 
 if(DOXYGEN_FOUND)
   set(abs_top_srcdir ${CMAKE_CURRENT_SOURCE_DIR}/..)
   set(DOT dot)
   set(PACKAGE_VERSION mainline)
   set(abs_top_builddir ..)
   configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doxygen.cfg.in
   ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg @ONLY)
 
   add_custom_target(lldb-cpp-doc
     ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg
     WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
     COMMENT "Generating LLDB C++ API reference with Doxygen" VERBATIM
   )
-endif(DOXYGEN_FOUND)
+endif()
 
-find_package(PythonInterp REQUIRED)
 find_program(EPYDOC_EXECUTABLE NAMES epydoc epydoc.py)
 if(EPYDOC_EXECUTABLE)
+  message(STATUS "Found epydoc - ${EPYDOC_EXECUTABLE}")
+
   find_program(DOT_EXECUTABLE dot)
-    if(DOT_EXECUTABLE)
-      set(EPYDOC_OPTIONS ${EPYDOC_OPTIONS} --graph all --dotpath ${DOT_EXECUTABLE})
-    endif()
-    set(DOC_DIR "${CMAKE_CURRENT_SOURCE_DIR}/doc")
-    file(MAKE_DIRECTORY "${DOC_DIR}")
-    #set(ENV{PYTHONPATH} ${CMAKE_CURRENT_BINARY_DIR}/../../../lib/python2.7/site-packages)
-    add_custom_target(lldb-python-doc
-      ${EPYDOC_EXECUTABLE}
-      --html
-      lldb
-      -o ${CMAKE_CURRENT_BINARY_DIR}/python_reference
-      --name "LLDB python API"
-      --url "http://lldb.llvm.org"
-      ${EPYDOC_OPTIONS}
-      DEPENDS swig_wrapper liblldb
-      WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/../../../lib${LLVM_LIBDIR_SUFFIX}/python2.7/site-packages
-      COMMENT "Generating LLDB Python API reference with epydoc" VERBATIM
-    )
-endif(EPYDOC_EXECUTABLE)
+    message(STATUS "Found dot - ${DOT_EXECUTABLE}")
+
+  # Pretend to make a python package so that we can generate the reference.
+  # Because we don't build liblldb, epydoc will complain that the import of
+  # _lldb.so failed, but that doesn't prevent it from generating the docs.
+  file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/lldb)
+  get_target_property(lldb_scripts_dir swig_wrapper BINARY_DIR)
+  add_custom_target(lldb-python-doc-package
+    COMMAND "${CMAKE_COMMAND}" -E copy "${lldb_scripts_dir}/lldb.py" "${CMAKE_CURRENT_BINARY_DIR}/lldb/__init__.py"
+    DEPENDS swig_wrapper
+    COMMENT "Copying lldb.py to pretend package.")
+
+    DEPENDS swig_wrapper
+    DEPENDS lldb-python-doc-package
+    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+else()
+  message(STATUS "Could NOT find epydoc")
+endif()
 
 if (LLVM_ENABLE_SPHINX)
   include(AddSphinxTarget)
   if (SPHINX_FOUND)
     if (${SPHINX_OUTPUT_HTML})
       add_sphinx_target(html lldb)
     endif()
   endif()
 endif()