maxjhandsome
/
llvm-project
forked from OSchip/llvm-project
1
0
Fork 0
Code Issues Pull Requests Packages Releases Wiki Activity
llvm-project/lldb/docs/CMakeLists.txt

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

54 lines
2.2 KiB
CMake
Raw Normal View History

Add CMake targets to build LLDB reference docs - [ninja|make] lldb-cpp-doc builds the C++ API reference docs - [ninja|make] lldb-python-doc builds the python API reference docs - updated build page on website to include instructions to build docs Tested on Linux/Mac OS X llvm-svn: 182752
2013-05-28 11:47:34 +08:00
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
)
[Docs] Generate the python reference without building all of LLDB 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. Differential revision: https://reviews.llvm.org/D61216 llvm-svn: 359465
2019-04-30 00:29:10 +08:00
endif()
Add CMake targets to build LLDB reference docs - [ninja|make] lldb-cpp-doc builds the C++ API reference docs - [ninja|make] lldb-python-doc builds the python API reference docs - updated build page on website to include instructions to build docs Tested on Linux/Mac OS X llvm-svn: 182752
2013-05-28 11:47:34 +08:00
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
2021-01-15 20:24:24 +08:00
if (LLVM_ENABLE_SPHINX)
include(AddSphinxTarget)
endif()
[Docs] Generate the python reference without building all of LLDB 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. Differential revision: https://reviews.llvm.org/D61216 llvm-svn: 359465
2019-04-30 00:29:10 +08:00
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
2021-01-15 20:24:24 +08:00
if (LLDB_ENABLE_PYTHON AND SPHINX_FOUND)
if (${SPHINX_OUTPUT_HTML})
# Pretend that the SWIG generated API is a Python package.
[Docs] Disable Python docs when LLDB_DISABLE_PYTHON is set This leads to a configuration error because we're trying to get a property that doesn't exist: get_target_property() called with non-existent target "swig_wrapper"
2019-10-29 00:49:58 +08:00
file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/lldb)
[lldb/CMake] Separate CMake code for Lua and Python (NFC) Separate the CMake logic for Lua and Python to clearly distinguish between code specific to either scripting language and the code shared by both. What this patch does is: - Move Python specific code into the bindings/python subdirectory. - Move the Lua specific code into the bindings/lua subdirectory. - Add the _python suffix to Python specific functions/targets. - Fix a dependency issue that would check the binding instead of whether the scripting language is enabled. Note that this patch also changes where the bindings are generated, which might affect downstream projects that check them in. Differential revision: https://reviews.llvm.org/D85708
2020-08-11 23:43:44 +08:00
get_target_property(lldb_bindings_dir swig_wrapper_python BINARY_DIR)
[Docs] Disable Python docs when LLDB_DISABLE_PYTHON is set This leads to a configuration error because we're trying to get a property that doesn't exist: get_target_property() called with non-existent target "swig_wrapper"
2019-10-29 00:49:58 +08:00
add_custom_target(lldb-python-doc-package
[lldb/Bindings] Move bindings into their own subdirectory All the code required to generate the language bindings for Python and Lua lives under scripts, even though the majority of this code aren't scripts at all, and surrounded by scripts that are totally unrelated. I've reorganized these files and moved everything related to the language bindings into a new top-level directory named bindings. This makes the corresponding files self contained and much more discoverable. Differential revision: https://reviews.llvm.org/D72437
2020-01-09 23:57:59 +08:00
COMMAND "${CMAKE_COMMAND}" -E copy "${lldb_bindings_dir}/lldb.py" "${CMAKE_CURRENT_BINARY_DIR}/lldb/__init__.py"
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
2021-01-15 20:24:24 +08:00
COMMENT "Copying lldb.py to pretend its a Python package.")
[lldb/CMake] Separate CMake code for Lua and Python (NFC) Separate the CMake logic for Lua and Python to clearly distinguish between code specific to either scripting language and the code shared by both. What this patch does is: - Move Python specific code into the bindings/python subdirectory. - Move the Lua specific code into the bindings/lua subdirectory. - Add the _python suffix to Python specific functions/targets. - Fix a dependency issue that would check the binding instead of whether the scripting language is enabled. Note that this patch also changes where the bindings are generated, which might affect downstream projects that check them in. Differential revision: https://reviews.llvm.org/D85708
2020-08-11 23:43:44 +08:00
add_dependencies(lldb-python-doc-package swig_wrapper_python)
[Docs] Generate the python reference without building all of LLDB 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. Differential revision: https://reviews.llvm.org/D61216 llvm-svn: 359465
2019-04-30 00:29:10 +08:00
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
2021-01-15 20:24:24 +08:00
# 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)
[Docs] Disable Python docs when LLDB_DISABLE_PYTHON is set This leads to a configuration error because we're trying to get a property that doesn't exist: get_target_property() called with non-existent target "swig_wrapper"
2019-10-29 00:49:58 +08:00
endif()
[Docs] Generate the LLDB man page with Sphinx This patch replaces the existing out-of-date man page for lldb and replaces it with an RST file from which sphinx generates the actual troff file. This is similar to how man pages are generated for the rest of the LLVM utilities. The man page is generated by building the `docs-lldb-man` target. Differential revision: https://reviews.llvm.org/D70514
2019-11-21 06:53:37 +08:00
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
2021-01-15 20:24:24 +08:00
if (${SPHINX_OUTPUT_MAN})
add_sphinx_target(man lldb)
Add LLDB website and documentation in reStructuredText for Sphinx The current LLDB website is written in HTML which is hard to maintain. We have quite a bit of HTML code checked in which can make it hard to differentiate between documentation written by us and documentation generated by a tool. In line with the other LLVM projects, I propose generating the documentation with Sphix. I think text/rst files provide a lower barrier for new or casual contributors to fix or update. This patch adds a copy of the LLDB website and documentation in reStructuredText. It also adds a new ninja target `docs-lldb-html` when -DLLVM_ENABLE_SPHINX:BOOL is enabled. This is the first step in having the website and documentation being generated from the repository, rather than having the output checked-in under the www folder. During the hopefully short transition period, please also update the reStructuredText files when modifying the website. Differential revision: https://reviews.llvm.org/D55376 llvm-svn: 352644
2019-01-31 02:51:40 +08:00
endif()
endif()