Skip to content

[SYCL] Enable documentation generation with Doxygen #878

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Dec 2, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions sycl/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -269,3 +269,6 @@ endforeach( comp )
add_custom_target(deploy-sycl-toolchain
DEPENDS sycl-toolchain ${manifest_list}
)

# SYCL Runtime documentation
add_subdirectory(doc)
80 changes: 80 additions & 0 deletions sycl/doc/CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
if (DOXYGEN_FOUND)
if (LLVM_ENABLE_DOXYGEN)
set(abs_srcdir ${CMAKE_CURRENT_SOURCE_DIR})
set(abs_builddir ${CMAKE_CURRENT_BINARY_DIR})

if (HAVE_DOT)
set(DOT ${LLVM_PATH_DOT})
endif()

# TODO add support for external search engine

if (LLVM_ENABLE_DOXYGEN_QT_HELP)
set(SYCL_DOXYGEN_QCH_FILENAME "org.llvm.sycl.qch" CACHE STRING
"Filename of the Qt Compressed help file")
set(SYCL_DOXYGEN_QHP_NAMESPACE "org.llvm.sycl" CACHE STRING
"Namespace under which the intermediate Qt Help Project file lives")
set(SYCL_DOXYGEN_QHP_CUST_FILTER_NAME "SYCL ${SYCL_VERSION}" CACHE STRING
"See http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters")
set(SYCL_DOXYGEN_QHP_CUST_FILTER_ATTRS "Clang,${SYCL_VERSION}" CACHE STRING
"See http://qt-project.org/doc/qt-4.8/qthelpproject.html#filter-attributes")
set(sycl_doxygen_generate_qhp "YES")
set(sycl_doxygen_qch_filename "${SYCL_DOXYGEN_QCH_FILENAME}")
set(sycl_doxygen_qhp_namespace "${SYCL_DOXYGEN_QHP_NAMESPACE}")
set(sycl_doxygen_qhelpgenerator_path "${LLVM_DOXYGEN_QHELPGENERATOR_PATH}")
set(sycl_doxygen_qhp_cust_filter_name "${SYCL_DOXYGEN_QHP_CUST_FILTER_NAME}")
set(sycl_doxygen_qhp_cust_filter_attrs "${SYCL_DOXYGEN_QHP_CUST_FILTER_ATTRS}")
else()
set(sycl_doxygen_generate_qhp "NO")
set(sycl_doxygen_qch_filename "")
set(sycl_doxygen_qhp_namespace "")
set(sycl_doxygen_qhelpgenerator_path "")
set(sycl_doxygen_qhp_cust_filter_name "")
set(sycl_doxygen_qhp_cust_filter_attrs "")
endif()

option(LLVM_DOXYGEN_SVG
"Use svg instead of png files for doxygen graphs." OFF)
if (LLVM_DOXYGEN_SVG)
set(DOT_IMAGE_FORMAT "svg")
else()
set(DOT_IMAGE_FORMAT "png")
endif()

configure_file(${CMAKE_CURRENT_SOURCE_DIR}/doxygen.cfg.in
${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg @ONLY)

set(abs_top_srcdir)
set(abs_top_builddir)
set(DOT)
set(enable_searchengine)
set(searchengine_url)
set(enable_server_based_search)
set(enable_external_search)
set(extra_search_mappings)
set(sycl_doxygen_generate_qhp)
set(sycl_doxygen_qch_filename)
set(sycl_doxygen_qhp_namespace)
set(sycl_doxygen_qhelpgenerator_path)
set(sycl_doxygen_qhp_cust_filter_name)
set(sycl_doxygen_qhp_cust_filter_attrs)
set(DOT_IMAGE_FORMAT)

add_custom_target(doxygen-sycl
COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.cfg
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
COMMENT "Generating sycl doxygen documentation." VERBATIM)

if (LLVM_BUILD_DOCS)
add_dependencies(doxygen doxygen-clang)
endif()

if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY)
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doxygen/html
DESTINATION docs/html)
endif()

endif()
endif()

# TODO enable sphinx
16 changes: 16 additions & 0 deletions sycl/doc/GetStartedWithSYCLCompiler.md
Original file line number Diff line number Diff line change
Expand Up @@ -242,6 +242,22 @@ cmake -DIntel_SYCL_ROOT=$SYCL_HOME/deploy -DSYCL_IMPLEMENTATION=Intel_SYCL ...
cmake -DIntel_SYCL_ROOT=%SYCL_HOME%\deploy -DSYCL_IMPLEMENTATION=Intel_SYCL ...
```

### Build Doxygen documentation

Building Doxygen documentation is similar to building the product itself. First,
the following tools need to be installed:
- doxygen
- graphviz

Then you'll need to add the following options to your CMake configuration
command:
```
-DLLVM_ENABLE_DOXYGEN=ON
```

After CMake cache is generated, build the documentation with `doxygen-sycl`
target. It will be put to `/path/to/build/tools/sycl/doc/html` directory.

## Run simple SYCL application

A simple SYCL program consists of following parts:
Expand Down
Loading