From ef98e70100751f4b3fd6b28b17b68a3c9991f092 Mon Sep 17 00:00:00 2001
From: Raphael Isemann <teemperor@gmail.com>
Date: Fri, 15 Jan 2021 13:24:24 +0100
Subject: [PATCH] Reland [lldb][docs] Use sphinx instead of epydoc to generate
 LLDB's Python reference

The build server should now have the missing dependencies.

Original summary:

Currently LLDB uses epydoc to generate the Python API reference for the website.
epydoc however is unmaintained since more than a decade and no longer works with
Python 3. Also whatever setup we had once for generating the documentation on
the website server no longer seems to work, so the current website documentation
has been stale since more than a year.

This patch replaces epydoc with sphinx and its automodapi plugin that can
generate Python API references. LLVM already uses sphinx for the rest of the
documentation, so this way we are more consistent with the rest of LLVM. The
only new dependency is the automodapi plugin for sphinx.

This patch effectively does the following things:
* Remove the epydoc code.
* Make a new dummy Python API page in our website that just calls the Sphinx
  command for generated the API documentation.
* Add a mock _lldb module that is only used when generating the Python API.
 This way we don't have to build all of LLDB to generate the API reference.

Some notes:
* The long list of skips is necessary due to boilerplate functions that SWIG
  is generating. Sadly automodapi is not really scriptable from what I can see,
  so we have to blacklist this stuff manually.
* The .gitignore change because automodapi wants a subfolder of our
  documentation directory to place generated documentation files there. The path
  is also what is used on the website, so we can't really workaround this
  (without copying the whole `docs` dir somewhere else when we build).
* We have to use environment variables to pass our build path to our sphinx
  configuration. Sphinx doesn't support passing variables onto that script.

Reviewed By: JDevlieghere

Differential Revision: https://reviews.llvm.org/D94489
---
 cmake/modules/AddSphinxTarget.cmake | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/cmake/modules/AddSphinxTarget.cmake b/cmake/modules/AddSphinxTarget.cmake
index b5babb30abc..e80c3b5c1ca 100644
--- a/cmake/modules/AddSphinxTarget.cmake
+++ b/cmake/modules/AddSphinxTarget.cmake
@@ -17,8 +17,13 @@ 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" "" ${ARGN})
+  cmake_parse_arguments(ARG "" "SOURCE_DIR" "ENV_VARS" ${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})
@@ -34,7 +39,8 @@ function (add_sphinx_target builder project)
   endif()
 
   add_custom_target(${SPHINX_TARGET_NAME}
-                    COMMAND ${SPHINX_EXECUTABLE}
+                    COMMAND ${CMAKE_COMMAND} -E env ${ARG_ENV_VARS}
+                            ${SPHINX_EXECUTABLE}
                             -b ${builder}
                             -d "${SPHINX_DOC_TREE_DIR}"
                             -q # Quiet: no output other than errors and warnings.