Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 9d2053f

Browse files
TeemperorTeemperor
committed
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.
1 parent 6edc3fe commit 9d2053f

7 files changed

Lines changed: 51 additions & 156 deletions

File tree

‎.gitignore‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -63,5 +63,3 @@ pythonenv*
6363
/clang/utils/analyzer/projects/*/PatchedSource
6464
/clang/utils/analyzer/projects/*/ScanBuildResults
6565
/clang/utils/analyzer/projects/*/RefScanBuildResults
66-
# automodapi puts generated documentation files here.
67-
/lldb/docs/python_api/

‎lldb/docs/CMakeLists.txt‎

Lines changed: 46 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -15,39 +15,60 @@ if(DOXYGEN_FOUND)
1515
)
1616
endif()
1717

18-
if (LLVM_ENABLE_SPHINX)
19-
include(AddSphinxTarget)
20-
endif()
18+
if (LLDB_ENABLE_PYTHON)
19+
find_program(EPYDOC_EXECUTABLE NAMES epydoc epydoc.py)
20+
if(EPYDOC_EXECUTABLE)
21+
message(STATUS "Found epydoc - ${EPYDOC_EXECUTABLE}")
22+
23+
find_program(DOT_EXECUTABLE dot)
24+
if(DOT_EXECUTABLE)
25+
set(EPYDOC_OPTIONS ${EPYDOC_OPTIONS} --graph all --dotpath ${DOT_EXECUTABLE})
26+
message(STATUS "Found dot - ${DOT_EXECUTABLE}")
27+
endif()
2128

22-
if (LLDB_ENABLE_PYTHON AND SPHINX_FOUND)
23-
if (${SPHINX_OUTPUT_HTML})
24-
# Pretend that the SWIG generated API is a Python package.
29+
# Pretend to make a python package so that we can generate the reference.
30+
# Because we don't build liblldb, epydoc will complain that the import of
31+
# _lldb.so failed, but that doesn't prevent it from generating the docs.
2532
file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/lldb)
2633
get_target_property(lldb_bindings_dir swig_wrapper_python BINARY_DIR)
2734
add_custom_target(lldb-python-doc-package
2835
COMMAND "${CMAKE_COMMAND}" -E copy "${lldb_bindings_dir}/lldb.py" "${CMAKE_CURRENT_BINARY_DIR}/lldb/__init__.py"
29-
COMMENT "Copying lldb.py to pretend its a Python package.")
36+
COMMENT "Copying lldb.py to pretend package.")
3037
add_dependencies(lldb-python-doc-package swig_wrapper_python)
3138

32-
# FIXME: Don't treat Sphinx warnings as errors. The files generated by
33-
# automodapi are full of warnings (partly caused by SWIG, our documentation
34-
# and probably also automodapi itself), so those warnings need to be fixed
35-
# first before we can turn this on.
36-
set(SPHINX_WARNINGS_AS_ERRORS Off)
37-
38-
# The sphinx config needs to know where the generated LLDB Python module is.
39-
# There is no way to pass a variable into our sphinx config, so just pass
40-
# the path to the module via the LLDB_SWIG_MODULE environment variable.
41-
add_sphinx_target(html lldb ENV_VARS "LLDB_SWIG_MODULE=${CMAKE_CURRENT_BINARY_DIR}")
42-
# Sphinx does not reliably update the custom CSS files, so force
43-
# a clean rebuild of the documentation every time.
44-
add_custom_target(clean-lldb-html COMMAND "${CMAKE_COMMAND}" -E
45-
remove_directory ${CMAKE_CURRENT_BINARY_DIR}/html)
46-
add_dependencies(docs-lldb-html swig_wrapper_python
47-
lldb-python-doc-package clean-lldb-html)
39+
set(DOC_DIR "${CMAKE_CURRENT_SOURCE_DIR}/doc")
40+
file(MAKE_DIRECTORY "${DOC_DIR}")
41+
add_custom_target(lldb-python-doc
42+
${EPYDOC_EXECUTABLE}
43+
--html
44+
lldb
45+
-o ${CMAKE_CURRENT_BINARY_DIR}/python_reference
46+
--name "LLDB python API"
47+
--url "http://lldb.llvm.org"
48+
${EPYDOC_OPTIONS}
49+
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
50+
COMMENT "Generating LLDB Python API reference with epydoc" VERBATIM
51+
)
52+
add_dependencies(lldb-python-doc swig_wrapper_python lldb-python-doc-package)
53+
else()
54+
message(STATUS "Could NOT find epydoc")
4855
endif()
56+
endif ()
57+
58+
if (LLVM_ENABLE_SPHINX)
59+
include(AddSphinxTarget)
60+
if (SPHINX_FOUND)
61+
if (${SPHINX_OUTPUT_HTML})
62+
add_sphinx_target(html lldb)
63+
# Sphinx does not reliably update the custom CSS files, so force
64+
# a clean rebuild of the documentation every time.
65+
add_custom_target(clean-lldb-html COMMAND "${CMAKE_COMMAND}" -E
66+
remove_directory ${CMAKE_CURRENT_BINARY_DIR}/html)
67+
add_dependencies(docs-lldb-html clean-lldb-html)
68+
endif()
4969

50-
if (${SPHINX_OUTPUT_MAN})
51-
add_sphinx_target(man lldb)
70+
if (${SPHINX_OUTPUT_MAN})
71+
add_sphinx_target(man lldb)
72+
endif()
5273
endif()
5374
endif()

‎lldb/docs/_lldb/__init__.py‎

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎lldb/docs/conf.py‎

Lines changed: 2 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -18,17 +18,7 @@
1818
# If extensions (or modules to document with autodoc) are in another directory,
1919
# add these directories to sys.path here. If the directory is relative to the
2020
# documentation root, use os.path.abspath to make it absolute, like shown here.
21-
22-
# Add the current directory that contains the mock _lldb native module which
23-
# is imported by the `lldb` module.
24-
sys.path.insert(0, os.path.abspath("."))
25-
# Add the build directory that contains the `lldb` module. LLDB_SWIG_MODULE is
26-
# set by CMake.
27-
sys.path.insert(0, os.getenv("LLDB_SWIG_MODULE"))
28-
29-
# Put the generated Python API documentation in the 'python_api' folder. This
30-
# also defines the URL these files will have in the generated website.
31-
automodapi_toctreedirnm = 'python_api'
21+
#sys.path.insert(0, os.path.abspath('.'))
3222

3323
# -- General configuration -----------------------------------------------------
3424

@@ -37,8 +27,7 @@
3727

3828
# Add any Sphinx extension module names here, as strings. They can be extensions
3929
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
40-
extensions = ['sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.intersphinx',
41-
'sphinx_automodapi.automodapi']
30+
extensions = ['sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.intersphinx']
4231

4332
# Add any paths that contain templates here, relative to this directory.
4433
templates_path = ['_templates']

‎lldb/docs/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -164,7 +164,7 @@ interesting areas to contribute to lldb.
164164
:maxdepth: 1
165165
:caption: Reference
166166

167-
Public Python API <python_api>
167+
Public Python API <https://lldb.llvm.org/python_reference/index.html>
168168
Public C++ API <https://lldb.llvm.org/cpp_reference/namespacelldb.html>
169169
Private C++ API <https://lldb.llvm.org/cpp_reference/index.html>
170170
Man Page <man/lldb>

‎lldb/docs/python_api.rst‎

Lines changed: 0 additions & 98 deletions
This file was deleted.

‎llvm/cmake/modules/AddSphinxTarget.cmake‎

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,8 @@ endif()
1717
# the sphinx-build command.
1818
#
1919
# ``project`` should be the project name
20-
#
21-
# Named arguments:
22-
# ``ENV_VARS`` should be a list of environment variables that should be set when
23-
# running Sphinx. Each environment variable should be a string with
24-
# the form KEY=VALUE.
2520
function (add_sphinx_target builder project)
26-
cmake_parse_arguments(ARG "" "SOURCE_DIR" "ENV_VARS" ${ARGN})
21+
cmake_parse_arguments(ARG "" "SOURCE_DIR" "" ${ARGN})
2722
set(SPHINX_BUILD_DIR "${CMAKE_CURRENT_BINARY_DIR}/${builder}")
2823
set(SPHINX_DOC_TREE_DIR "${CMAKE_CURRENT_BINARY_DIR}/_doctrees-${project}-${builder}")
2924
set(SPHINX_TARGET_NAME docs-${project}-${builder})
@@ -39,8 +34,7 @@ function (add_sphinx_target builder project)
3934
endif()
4035

4136
add_custom_target(${SPHINX_TARGET_NAME}
42-
COMMAND ${CMAKE_COMMAND} -E env ${ARG_ENV_VARS}
43-
${SPHINX_EXECUTABLE}
37+
COMMAND ${SPHINX_EXECUTABLE}
4438
-b ${builder}
4539
-d "${SPHINX_DOC_TREE_DIR}"
4640
-q # Quiet: no output other than errors and warnings.

0 commit comments

Comments
 (0)