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.

Sign up for GitHub

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
+2,595 −0
Merged

[SYCL] Enable documentation generation with Doxygen #878

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
495e13e
[SYCL] Enable documentation generation with Doxygen
Nov 7, 2019
85c5099
Apply comments
Nov 28, 2019
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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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