Skip to content

Commit de418d6

Browse files
Alexander Batashevbader
Alexander Batashev
authored and
bader
committed
[SYCL] Enable documentation generation with Doxygen (#878)
Add doxygen-sycl target and make it process source code with Doxygen to emit documentation. Generated HTML files can be found in /path/to/build/tools/sycl/doc/html Signed-off-by: Alexander Batashev <[email protected]>
1 parent 7f2f668 commit de418d6

File tree

4 files changed

+2595
-0
lines changed

4 files changed

+2595
-0
lines changed

‎sycl/CMakeLists.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -269,3 +269,6 @@ endforeach( comp )
269269
add_custom_target(deploy-sycl-toolchain
270270
DEPENDS sycl-toolchain ${manifest_list}
271271
)
272+
273+
# SYCL Runtime documentation
274+
add_subdirectory(doc)

‎sycl/doc/CMakeLists.txt

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
if (DOXYGEN_FOUND)
2+
if (LLVM_ENABLE_DOXYGEN)
3+
set(abs_srcdir ${CMAKE_CURRENT_SOURCE_DIR})
4+
set(abs_builddir ${CMAKE_CURRENT_BINARY_DIR})
5+
6+
if (HAVE_DOT)
7+
set(DOT ${LLVM_PATH_DOT})
8+
endif()
9+
10+
# TODO add support for external search engine
11+
12+
if (LLVM_ENABLE_DOXYGEN_QT_HELP)
13+
set(SYCL_DOXYGEN_QCH_FILENAME "org.llvm.sycl.qch" CACHE STRING
14+
"Filename of the Qt Compressed help file")
15+
set(SYCL_DOXYGEN_QHP_NAMESPACE "org.llvm.sycl" CACHE STRING
16+
"Namespace under which the intermediate Qt Help Project file lives")
17+
set(SYCL_DOXYGEN_QHP_CUST_FILTER_NAME "SYCL ${SYCL_VERSION}" CACHE STRING
18+
"See http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters")
19+
set(SYCL_DOXYGEN_QHP_CUST_FILTER_ATTRS "Clang,${SYCL_VERSION}" CACHE STRING
20+
"See http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes")
21+
set(sycl_doxygen_generate_qhp "YES")
22+
set(sycl_doxygen_qch_filename "${SYCL_DOXYGEN_QCH_FILENAME}")
23+
set(sycl_doxygen_qhp_namespace "${SYCL_DOXYGEN_QHP_NAMESPACE}")
24+
set(sycl_doxygen_qhelpgenerator_path "${LLVM_DOXYGEN_QHELPGENERATOR_PATH}")
25+
set(sycl_doxygen_qhp_cust_filter_name "${SYCL_DOXYGEN_QHP_CUST_FILTER_NAME}")
26+
set(sycl_doxygen_qhp_cust_filter_attrs "${SYCL_DOXYGEN_QHP_CUST_FILTER_ATTRS}")
27+
else()
28+
set(sycl_doxygen_generate_qhp "NO")
29+
set(sycl_doxygen_qch_filename "")
30+
set(sycl_doxygen_qhp_namespace "")
31+
set(sycl_doxygen_qhelpgenerator_path "")
32+
set(sycl_doxygen_qhp_cust_filter_name "")
33+
set(sycl_doxygen_qhp_cust_filter_attrs "")
34+
endif()
35+
36+
option(LLVM_DOXYGEN_SVG
37+
"Use svg instead of png files for doxygen graphs." OFF)
38+
if (LLVM_DOXYGEN_SVG)
39+
set(DOT_IMAGE_FORMAT "svg")
40+
else()
41+
set(DOT_IMAGE_FORMAT "png")
42+
endif()
43+
44+
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doxygen.cfg.in
45+
${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg @ONLY)
46+
47+
set(abs_top_srcdir)
48+
set(abs_top_builddir)
49+
set(DOT)
50+
set(enable_searchengine)
51+
set(searchengine_url)
52+
set(enable_server_based_search)
53+
set(enable_external_search)
54+
set(extra_search_mappings)
55+
set(sycl_doxygen_generate_qhp)
56+
set(sycl_doxygen_qch_filename)
57+
set(sycl_doxygen_qhp_namespace)
58+
set(sycl_doxygen_qhelpgenerator_path)
59+
set(sycl_doxygen_qhp_cust_filter_name)
60+
set(sycl_doxygen_qhp_cust_filter_attrs)
61+
set(DOT_IMAGE_FORMAT)
62+
63+
add_custom_target(doxygen-sycl
64+
COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg
65+
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
66+
COMMENT "Generating sycl doxygen documentation." VERBATIM)
67+
68+
if (LLVM_BUILD_DOCS)
69+
add_dependencies(doxygen doxygen-clang)
70+
endif()
71+
72+
if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY)
73+
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doxygen/html
74+
DESTINATION docs/html)
75+
endif()
76+
77+
endif()
78+
endif()
79+
80+
# TODO enable sphinx

‎sycl/doc/GetStartedWithSYCLCompiler.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -242,6 +242,22 @@ cmake -DIntel_SYCL_ROOT=$SYCL_HOME/deploy -DSYCL_IMPLEMENTATION=Intel_SYCL ...
242242
cmake -DIntel_SYCL_ROOT=%SYCL_HOME%\deploy -DSYCL_IMPLEMENTATION=Intel_SYCL ...
243243
```
244244

245+
### Build Doxygen documentation
246+
247+
Building Doxygen documentation is similar to building the product itself. First,
248+
the following tools need to be installed:
249+
- doxygen
250+
- graphviz
251+
252+
Then you'll need to add the following options to your CMake configuration
253+
command:
254+
```
255+
-DLLVM_ENABLE_DOXYGEN=ON
256+
```
257+
258+
After CMake cache is generated, build the documentation with `doxygen-sycl`
259+
target. It will be put to `/path/to/build/tools/sycl/doc/html` directory.
260+
245261
## Run simple SYCL application
246262

247263
A simple SYCL program consists of following parts:

0 commit comments

Comments
 (0)