[clang] 87d8ae7 - [clang][cmake] Include generated rst files in html built by docs-clang-html target
Tom Stellard via cfe-commits
cfe-commits at lists.llvm.org
Thu Mar 5 21:40:37 PST 2020
Author: Tom Stellard
Date: 2020-03-05T21:30:37-08:00
New Revision: 87d8ae700b80d58d69bb92b601f946f02f089398
URL: https://github.com/llvm/llvm-project/commit/87d8ae700b80d58d69bb92b601f946f02f089398
DIFF: https://github.com/llvm/llvm-project/commit/87d8ae700b80d58d69bb92b601f946f02f089398.diff
LOG: [clang][cmake] Include generated rst files in html built by docs-clang-html target
Summary:
This is an attempt to simply the process of building the clang
documentation, which should help avoid some of the recent issues we've
had generating the documentation for the website.
The html documentation for clang is generated by sphinx from the
reStructuredText (rst) files we have in the clang/docs directory.
There are also some rst files that need to be generated by TableGen,
before they can be passed to sphinx. Prior to this patch we were not
generating those rst files as part with the build system and they had to be
generated manually.
This patch enables the automatic generation of these rst files, but
since they are generated at build time the cannot be placed in the
clang/docs directory and must go into the cmake build directory.
Unfortunately sphinx does not currently support multiple source
directories[1], so in order to be able to generate the full
documentation, we need to work around this by copying the
rst files from the clang/docs into the build directory before
generating the html documentation.
[1] https://github.com/sphinx-doc/sphinx/issues/3132
Reviewers: rsmith, aaron.ballman, beanz, smeenai, phosek, compnerd, mgorny, delcypher
Reviewed By: mgorny, delcypher
Subscribers: delcypher, merge_guards_bot, mgorny, llvm-commits, cfe-commits
Tags: #clang, #llvm
Differential Revision: https://reviews.llvm.org/D72875
Added:
Modified:
clang/docs/CMakeLists.txt
llvm/cmake/modules/AddSphinxTarget.cmake
Removed:
clang/docs/AttributeReference.rst
################################################################################
diff --git a/clang/docs/AttributeReference.rst b/clang/docs/AttributeReference.rst
deleted file mode 100644
index a763ddeaeb10..000000000000
--- a/clang/docs/AttributeReference.rst
+++ /dev/null
@@ -1,13 +0,0 @@
-..
- -------------------------------------------------------------------
- NOTE: This file is automatically generated by running clang-tblgen
- -gen-attr-docs. Do not edit this file by hand!! The contents for
- this file are automatically generated by a server-side process.
-
- Please do not commit this file. The file exists for local testing
- purposes only.
- -------------------------------------------------------------------
-
-===================
-Attributes in Clang
-===================
\ No newline at end of file
diff --git a/clang/docs/CMakeLists.txt b/clang/docs/CMakeLists.txt
index d2956c18f80c..221ac302579b 100644
--- a/clang/docs/CMakeLists.txt
+++ b/clang/docs/CMakeLists.txt
@@ -90,15 +90,43 @@ if (LLVM_ENABLE_DOXYGEN)
endif()
endif()
+function (gen_rst_file_from_td output_file td_option source docs_target)
+ if (NOT EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/${source}")
+ message(FATAL_ERROR "Cannot find source file: ${source} in ${CMAKE_CURRENT_SOURCE_DIR}")
+ endif()
+ get_filename_component(TABLEGEN_INCLUDE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/${source}" DIRECTORY)
+ list(APPEND LLVM_TABLEGEN_FLAGS "-I${TABLEGEN_INCLUDE_DIR}")
+ clang_tablegen(${output_file} ${td_option} SOURCE ${source} TARGET "gen-${output_file}")
+ add_dependencies(${docs_target} "gen-${output_file}")
+endfunction()
+
if (LLVM_ENABLE_SPHINX)
include(AddSphinxTarget)
if (SPHINX_FOUND)
if (${SPHINX_OUTPUT_HTML})
- add_sphinx_target(html clang)
+ add_sphinx_target(html clang SOURCE_DIR "${CMAKE_CURRENT_BINARY_DIR}")
+
+ # Copy rst files to build directory before generating the html
+ # documentation. Some of the rst files are generated, so they
+ # only exist in the build directory. Sphinx needs all files in
+ # the same directory in order to genrate the html, so we need to
+ # copy all the non-gnerated rst files from the source to the build
+ # directory before we run sphinx.
+ add_custom_target(copy-clang-rst-docs
+ COMMAND "${CMAKE_COMMAND}" -E copy_directory
+ "${CMAKE_CURRENT_SOURCE_DIR}"
+ "${CMAKE_CURRENT_BINARY_DIR}")
+ add_dependencies(docs-clang-html copy-clang-rst-docs)
+
add_custom_command(TARGET docs-clang-html POST_BUILD
- COMMAND ${CMAKE_COMMAND} -E copy
+ COMMAND "${CMAKE_COMMAND}" -E copy
"${CMAKE_CURRENT_SOURCE_DIR}/LibASTMatchersReference.html"
"${CMAKE_CURRENT_BINARY_DIR}/html/LibASTMatchersReference.html")
+
+ # Generated files
+ gen_rst_file_from_td(AttributeReference.rst -gen-attr-docs ../include/clang/Basic/Attr.td docs-clang-html)
+ gen_rst_file_from_td(DiagnosticsReference.rst -gen-diag-docs ../include/clang/Basic/Diagnostic.td docs-clang-html)
+ gen_rst_file_from_td(ClangCommandLineReference.rst -gen-opt-docs ../include/clang/Driver/ClangOptionDocs.td docs-clang-html)
endif()
if (${SPHINX_OUTPUT_MAN})
add_sphinx_target(man clang)
diff --git a/llvm/cmake/modules/AddSphinxTarget.cmake b/llvm/cmake/modules/AddSphinxTarget.cmake
index 2bf654b60c44..f053d8084da4 100644
--- a/llvm/cmake/modules/AddSphinxTarget.cmake
+++ b/llvm/cmake/modules/AddSphinxTarget.cmake
@@ -18,6 +18,7 @@ endif()
#
# ``project`` should be the project name
function (add_sphinx_target builder project)
+ 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})
@@ -28,13 +29,17 @@ function (add_sphinx_target builder project)
set(SPHINX_WARNINGS_AS_ERRORS_FLAG "")
endif()
+ if (NOT ARG_SOURCE_DIR)
+ set(ARG_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
+ endif()
+
add_custom_target(${SPHINX_TARGET_NAME}
COMMAND ${SPHINX_EXECUTABLE}
-b ${builder}
-d "${SPHINX_DOC_TREE_DIR}"
-q # Quiet: no output other than errors and warnings.
${SPHINX_WARNINGS_AS_ERRORS_FLAG} # Treat warnings as errors if requested
- "${CMAKE_CURRENT_SOURCE_DIR}" # Source
+ "${ARG_SOURCE_DIR}" # Source
"${SPHINX_BUILD_DIR}" # Output
COMMENT
"Generating ${builder} Sphinx documentation for ${project} into \"${SPHINX_BUILD_DIR}\"")
More information about the cfe-commits
mailing list