e7bc6c594b
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
54 lines
2.2 KiB
CMake
54 lines
2.2 KiB
CMake
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()
|
|
|
|
if (LLVM_ENABLE_SPHINX)
|
|
include(AddSphinxTarget)
|
|
endif()
|
|
|
|
if (LLDB_ENABLE_PYTHON AND SPHINX_FOUND)
|
|
if (${SPHINX_OUTPUT_HTML})
|
|
# Pretend that the SWIG generated API is a Python package.
|
|
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.")
|
|
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)
|
|
endif()
|
|
|
|
if (${SPHINX_OUTPUT_MAN})
|
|
add_sphinx_target(man lldb)
|
|
endif()
|
|
endif()
|