Skip to content

Commit 092e00c

Browse files
diptorupddiptorupd
authored
Sphinx and Doxygen documentation (#140)
* Adding the basic infrastructure to generate API docs for dpCtl. * Add missing doxygen doc-strings. * Various improvements to Python doc-strings and documentation. * Add Sphinx documentation for dpctl.memory.
1 parent 138de94 commit 092e00c

17 files changed

+3117
-164
lines changed

‎backends/include/Support/CBindingWrapping.h‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,10 @@
2525

2626
#pragma once
2727

28+
/*!
29+
@brief Creates two convenience functions to reinterpret_cast an opaque
30+
pointer to a pointer to a Sycl type and vice-versa.
31+
*/
2832
#define DEFINE_SIMPLE_CONVERSION_FUNCTIONS(ty, ref) \
2933
__attribute__((unused)) inline ty *unwrap(ref P) \
3034
{ \
@@ -36,7 +40,11 @@
3640
return reinterpret_cast<ref>(const_cast<ty*>(P)); \
3741
}
3842

39-
#define DEFINE_STDCXX_CONVERSION_FUNCTIONS(ty, ref) \
43+
/*!
44+
@brief Add an overloaded unwrap to assert that a pointer can be legally
45+
cast. @see DEFINE_SIMPLE_CONVERSION_FUNCTIONS()
46+
*/
47+
#define DEFINE_STDCXX_CONVERSION_FUNCTIONS(ty, ref) \
4048
DEFINE_SIMPLE_CONVERSION_FUNCTIONS(ty, ref) \
4149
\
4250
template<typename T> \

‎backends/include/dppl_data_types.h‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,17 +76,30 @@ typedef signed int ssize_t;
7676

7777
#endif /* _MSC_VER */
7878

79-
/* Set defaults for constants which we cannot find. */
79+
/*!
80+
@brief Represents tha largest possible value of a 64 bit signed integer.
81+
*/
8082
#if !defined(INT64_MAX)
8183
# define INT64_MAX 9223372036854775807LL
8284
#endif
85+
86+
/*!
87+
@brief Represents tha smallest possible value of a 64 bit signed integer.
88+
*/
8389
#if !defined(INT64_MIN)
8490
# define INT64_MIN ((-INT64_MAX)-1)
8591
#endif
92+
93+
/*!
94+
@brief Represents tha largest possible value of a 64bit unsigned integer.
95+
*/
8696
#if !defined(UINT64_MAX)
8797
# define UINT64_MAX 0xffffffffffffffffULL
8898
#endif
8999

100+
/*!
101+
@brief Represents a positive expression of type float.
102+
*/
90103
#ifndef HUGE_VALF
91104
#define HUGE_VALF (float)HUGE_VAL
92105
#endif

‎backends/include/dppl_sycl_program_interface.h‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@ DPPL_C_EXTERN_C_BEGIN
5252
*
5353
* @param Ctx An opaque pointer to a sycl::context
5454
* @param IL SPIR-V binary
55+
* @param Length The size of the IL binary in bytes.
5556
* @return A new SyclProgramRef pointer if the program creation succeeded,
5657
* else returns NULL.
5758
*/
@@ -66,7 +67,7 @@ DPPLProgram_CreateFromOCLSpirv (__dppl_keep const DPPLSyclContextRef Ctx,
6667
*
6768
* @param Ctx An opaque pointer to a sycl::context
6869
* @param Source OpenCL source string
69-
* @param CompileOptions Extra compiler flags (refer Sycl spec.)
70+
* @param CompileOpts Extra compiler flags (refer Sycl spec.)
7071
* @return A new SyclProgramRef pointer if the program creation succeeded,
7172
* else returns NULL.
7273
*/

‎backends/include/dppl_sycl_queue_manager.h‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,7 @@ __dppl_give DPPLSyclQueueRef DPPLQueueMgr_GetCurrentQueue ();
5656
/*!
5757
* @brief Get a sycl::queue object of the specified type and device id.
5858
*
59+
* @param BETy A valid Sycl backend value.
5960
* @param DeviceTy The type of Sycl device (sycl_device_type)
6061
* @param DNum Device id for the device (defaults to 0)
6162
*

‎docs/.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
docs
2+
generated_docs
3+
api
4+
build
5+
conf.py

‎docs/CMakeLists.txt‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
cmake_minimum_required(VERSION 3.18 FATAL_ERROR)
2+
project("Data-parallel Control (dpCtl)")
3+
# Add the cmake folder so the FindSphinx module is found
4+
set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake" ${CMAKE_MODULE_PATH})
5+
6+
find_package(Sphinx REQUIRED)
7+
find_package(Doxygen REQUIRED)
8+
find_package (Git)
9+
10+
set(DOC_OUTPUT_DIR ${CMAKE_CURRENT_SOURCE_DIR}/generated_docs)
11+
if( DPCTL_DOCGEN_PREFIX )
12+
message(STATUS "Generating dpCtl documents in " ${DPCTL_DOCGEN_PREFIX})
13+
set(DOC_OUTPUT_DIR ${DPCTL_DOCGEN_PREFIX})
14+
endif()
15+
16+
set(CURRENT_RELEASE "")
17+
18+
# Use git describe to get latest tag name
19+
if (GIT_FOUND)
20+
execute_process(
21+
COMMAND ${GIT_EXECUTABLE} describe --tags --abbrev=0
22+
RESULT_VARIABLE result
23+
OUTPUT_VARIABLE CURRENT_RELEASE
24+
OUTPUT_STRIP_TRAILING_WHITESPACE
25+
)
26+
endif (GIT_FOUND)
27+
28+
set(DOXYGEN_INPUT_DIR ../backends)
29+
set(DOXYGEN_OUTPUT_DIR ${DOC_OUTPUT_DIR}/doxygen)
30+
set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/html/index.html)
31+
set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
32+
set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
33+
34+
# Replace variables inside @@ with the current values
35+
configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
36+
37+
file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})
38+
39+
add_custom_command(
40+
OUTPUT ${DOXYGEN_INDEX_FILE}
41+
DEPENDS ${DPCTL_PUBLIC_HEADERS}
42+
COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
43+
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
44+
MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
45+
COMMENT "Generating Doxygen documentation"
46+
VERBATIM
47+
)
48+
49+
set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
50+
set(SPHINX_OUTPUT_DIR ${DOC_OUTPUT_DIR}/docs)
51+
set(SPHINX_INDEX_FILE ${SPHINX_OUTPUT_DIR}/index.html)
52+
set(SPHINX_CONF_IN ${SPHINX_SOURCE}/conf.in)
53+
set(SPHINX_CONF_OUT ${SPHINX_SOURCE}/conf.py)
54+
55+
# Create a conf.py by replacing variables inside @@ with the current values
56+
configure_file(${SPHINX_CONF_IN} ${SPHINX_CONF_OUT} @ONLY)
57+
58+
# Only regenerate Sphinx when:
59+
# - Doxygen has rerun
60+
# - Our doc files have been updated
61+
# - The Sphinx config has been updated
62+
add_custom_command(
63+
OUTPUT ${SPHINX_INDEX_FILE}
64+
COMMAND
65+
${SPHINX_EXECUTABLE} -b html
66+
# Tell Breathe where to find the Doxygen output
67+
-Dbreathe_projects.dpCtl-CAPI=${DOXYGEN_OUTPUT_DIR}/xml
68+
${SPHINX_SOURCE} ${SPHINX_OUTPUT_DIR}
69+
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
70+
DEPENDS
71+
# Other docs files that can be edited manually
72+
${CMAKE_CURRENT_SOURCE_DIR}/index.rst
73+
${DOXYGEN_INDEX_FILE}
74+
MAIN_DEPENDENCY ${SPHINX_CONF_OUT} ${SPHINX_CONF_IN}
75+
COMMENT "Generating Sphinx documentation"
76+
)
77+
78+
# Target to generate only Doxygen documentation
79+
add_custom_target(
80+
Doxygen
81+
ALL
82+
DEPENDS ${DOXYGEN_INDEX_FILE}
83+
)
84+
85+
# Target to generate all documentation Sphinx and Doxygen
86+
add_custom_target(
87+
Sphinx
88+
ALL
89+
DEPENDS Doxygen ${SPHINX_INDEX_FILE}
90+
)

0 commit comments

Comments
 (0)