Revert "[lldb][docs] Use sphinx instead of epydoc to generate LLDB's Python reference"

This reverts commit bab121a. It seems the
docs buildbot doesn't have the required Python headers.

Author: Teemperor

.gitignore

@@ -63,5 +63,3 @@ pythonenv*
 /clang/utils/analyzer/projects/*/PatchedSource
 /clang/utils/analyzer/projects/*/ScanBuildResults
 /clang/utils/analyzer/projects/*/RefScanBuildResults
-# automodapi puts generated documentation files here.
-/lldb/docs/python_api/

lldb/docs/CMakeLists.txt

@@ -15,39 +15,60 @@ if(DOXYGEN_FOUND)
   )
 endif()
 
-if (LLVM_ENABLE_SPHINX)
-  include(AddSphinxTarget)
-endif()
+if (LLDB_ENABLE_PYTHON)
+  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})
+      message(STATUS "Found dot - ${DOT_EXECUTABLE}")
+    endif()
 
-if (LLDB_ENABLE_PYTHON AND SPHINX_FOUND)
-  if (${SPHINX_OUTPUT_HTML})
-    # Pretend that the SWIG generated API is a Python package.
+    # 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_bindings_dir swig_wrapper_python BINARY_DIR)
     add_custom_target(lldb-python-doc-package
       COMMAND "${CMAKE_COMMAND}" -E copy "${lldb_bindings_dir}/lldb.py" "${CMAKE_CURRENT_BINARY_DIR}/lldb/__init__.py"
-      COMMENT "Copying lldb.py to pretend its a Python package.")
+      COMMENT "Copying lldb.py to pretend package.")
     add_dependencies(lldb-python-doc-package swig_wrapper_python)
 
-    # FIXME: Don't treat Sphinx warnings as errors. The files generated by
-    # automodapi are full of warnings (partly caused by SWIG, our documentation
-    # and probably also automodapi itself), so those warnings need to be fixed
-    # first before we can turn this on.
-    set(SPHINX_WARNINGS_AS_ERRORS Off)
-
-    # The sphinx config needs to know where the generated LLDB Python module is.
-    # There is no way to pass a variable into our sphinx config, so just pass
-    # the path to the module via the LLDB_SWIG_MODULE environment variable.
-    add_sphinx_target(html lldb ENV_VARS "LLDB_SWIG_MODULE=${CMAKE_CURRENT_BINARY_DIR}")
-    # Sphinx does not reliably update the custom CSS files, so force
-    # a clean rebuild of the documentation every time.
-    add_custom_target(clean-lldb-html COMMAND "${CMAKE_COMMAND}" -E
-      remove_directory ${CMAKE_CURRENT_BINARY_DIR}/html)
-    add_dependencies(docs-lldb-html swig_wrapper_python
-                     lldb-python-doc-package clean-lldb-html)
+    set(DOC_DIR "${CMAKE_CURRENT_SOURCE_DIR}/doc")
+    file(MAKE_DIRECTORY "${DOC_DIR}")
+    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}
+      WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+      COMMENT "Generating LLDB Python API reference with epydoc" VERBATIM
+    )
+    add_dependencies(lldb-python-doc swig_wrapper_python lldb-python-doc-package)
+  else()
+    message(STATUS "Could NOT find epydoc")
   endif()
+endif ()
+
+if (LLVM_ENABLE_SPHINX)
+  include(AddSphinxTarget)
+  if (SPHINX_FOUND)
+    if (${SPHINX_OUTPUT_HTML})
+      add_sphinx_target(html lldb)
+      # Sphinx does not reliably update the custom CSS files, so force
+      # a clean rebuild of the documentation every time.
+      add_custom_target(clean-lldb-html COMMAND "${CMAKE_COMMAND}" -E
+        remove_directory ${CMAKE_CURRENT_BINARY_DIR}/html)
+      add_dependencies(docs-lldb-html clean-lldb-html)
+    endif()
 
-  if (${SPHINX_OUTPUT_MAN})
-    add_sphinx_target(man lldb)
+    if (${SPHINX_OUTPUT_MAN})
+      add_sphinx_target(man lldb)
+    endif()
   endif()
 endif()

lldb/docs/_lldb/__init__.py

@@ -18,17 +18,7 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-
-# Add the current directory that contains the mock _lldb native module which
-# is imported by the `lldb` module.
-sys.path.insert(0, os.path.abspath("."))
-# Add the build directory that contains the `lldb` module. LLDB_SWIG_MODULE is
-# set by CMake.
-sys.path.insert(0, os.getenv("LLDB_SWIG_MODULE"))
-
-# Put the generated Python API documentation in the 'python_api' folder. This
-# also defines the URL these files will have in the generated website.
-automodapi_toctreedirnm = 'python_api'
+#sys.path.insert(0, os.path.abspath('.'))
 
 # -- General configuration -----------------------------------------------------
 
@@ -37,8 +27,7 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.intersphinx',
-              'sphinx_automodapi.automodapi']
+extensions = ['sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.intersphinx']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

lldb/docs/conf.py

@@ -164,7 +164,7 @@ interesting areas to contribute to lldb.
    :maxdepth: 1
    :caption: Reference
 
-   Public Python API <python_api>
+   Public Python API <https://lldb.llvm.org/python_reference/index.html>
    Public C++ API <https://lldb.llvm.org/cpp_reference/namespacelldb.html>
    Private C++ API <https://lldb.llvm.org/cpp_reference/index.html>
    Man Page <man/lldb>

lldb/docs/index.rst

@@ -17,13 +17,8 @@ endif()
 # the sphinx-build command.
 #
 # ``project`` should be the project name
-#
-# Named arguments:
-# ``ENV_VARS`` should be a list of environment variables that should be set when
-#              running Sphinx. Each environment variable should be a string with
-#              the form KEY=VALUE.
 function (add_sphinx_target builder project)
-  cmake_parse_arguments(ARG "" "SOURCE_DIR" "ENV_VARS" ${ARGN})
+  cmake_parse_arguments(ARG "" "SOURCE_DIR" "" ${ARGN})
   set(SPHINX_BUILD_DIR "${CMAKE_CURRENT_BINARY_DIR}/${builder}")
   set(SPHINX_DOC_TREE_DIR "${CMAKE_CURRENT_BINARY_DIR}/_doctrees-${project}-${builder}")
   set(SPHINX_TARGET_NAME docs-${project}-${builder})
@@ -39,8 +34,7 @@ function (add_sphinx_target builder project)
   endif()
 
   add_custom_target(${SPHINX_TARGET_NAME}
-                    COMMAND ${CMAKE_COMMAND} -E env ${ARG_ENV_VARS}
-                            ${SPHINX_EXECUTABLE}
+                    COMMAND ${SPHINX_EXECUTABLE}
                             -b ${builder}
                             -d "${SPHINX_DOC_TREE_DIR}"
                             -q # Quiet: no output other than errors and warnings.