Skip to content

Commit f5cd7c7

Browse files
author
Diptorup Deb
authored
Merge pull request #397 from diptorupd/feature/doc-infra-improvements
Feature/documentation infrastructure improvements
2 parents 82eed52 + 0d61611 commit f5cd7c7

28 files changed

+1503
-258
lines changed

‎docs/.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
docs
22
generated_docs
3+
docfiles/dpctl-capi
34
api
45
build
56
conf.py
7+
index.rst
8+
doxyrest-config.lua

‎docs/CMakeLists.txt

+188-88
Original file line numberDiff line numberDiff line change
@@ -1,100 +1,200 @@
11
cmake_minimum_required(VERSION 3.18 FATAL_ERROR)
22
project("Data-parallel Control (dpctl)")
3+
4+
# Option to generate rst for C API and add to Sphinx documentation
5+
option(DPCTL_ENABLE_DOXYREST
6+
"Enable generation of rst files for C API"
7+
OFF
8+
)
9+
10+
# Option to add verion links to the side bar. This option is primarily
11+
# intended to generate dpctl's docs for our github.io page.
12+
option(DPCTL_USE_MULTIVERSION_TEMPLATE
13+
"Enable adding verion links to side bar"
14+
OFF
15+
)
16+
17+
# This function defines everything needed to generate Doxygen docs
18+
function(_setup_doxygen)
19+
# We generate doxygen only for the public headers to keep the Doxyrest
20+
# generated rst files clean.
21+
# FIXME: make it possible to generate doxygen for all files.
22+
set(DOXYGEN_INPUT_DIR ../dpctl-capi/include)
23+
set(DOXYGEN_OUTPUT_DIR ${DOC_OUTPUT_DIR}/doxygen)
24+
set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/xml/index.xml)
25+
set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
26+
set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
27+
28+
# Populate the configurable values in the Doxyfile.in and
29+
# generate the actual Doxyfile.
30+
configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
31+
32+
file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})
33+
34+
# Custom command to run Doxygen
35+
add_custom_command(
36+
OUTPUT ${DOXYGEN_INDEX_FILE}
37+
DEPENDS ${DPCTL_PUBLIC_HEADERS}
38+
COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
39+
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
40+
MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
41+
COMMENT "Generating Doxygen documentation"
42+
VERBATIM
43+
)
44+
45+
# Target to generate only Doxygen documentation
46+
add_custom_target(
47+
Doxygen
48+
ALL
49+
DEPENDS ${DOXYGEN_INDEX_FILE}
50+
)
51+
endfunction()
52+
53+
function(_setup_doxyrest)
54+
set(DOXYREST_OUTPUT_DIR_NAME docfiles/dpctl-capi)
55+
set(DOXYREST_OUTPUT_DIR
56+
${CMAKE_CURRENT_SOURCE_DIR}/${DOXYREST_OUTPUT_DIR_NAME}
57+
PARENT_SCOPE
58+
)
59+
set(DOXYREST_OUTPUT_DIR
60+
${CMAKE_CURRENT_SOURCE_DIR}/${DOXYREST_OUTPUT_DIR_NAME}
61+
62+
)
63+
set(DOXYREST_CONFIG_IN ${CMAKE_CURRENT_SOURCE_DIR}/doxyrest-config.lua.in)
64+
set(DOXYREST_CONFIG_OUT ${CMAKE_CURRENT_SOURCE_DIR}/doxyrest-config.lua)
65+
set(DOXYREST_OUTPUT ${DOXYREST_OUTPUT_DIR}/index.rst)
66+
set(DOXYGEN_OUTPUT_DIR ${DOC_OUTPUT_DIR}/doxygen)
67+
configure_file(${DOXYREST_CONFIG_IN} ${DOXYREST_CONFIG_OUT} @ONLY)
68+
configure_file(${INDEX_DOXYREST_IN} ${INDEX_OUT} @ONLY)
69+
add_custom_command(
70+
OUTPUT ${DOXYREST_OUTPUT}
71+
COMMAND
72+
${DOXYREST_EXE} -c
73+
${DOXYREST_CONFIG_OUT}
74+
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
75+
DEPENDS
76+
# Other docs files that can be edited manually
77+
${INDEX_OUT}
78+
${DOXYGEN_INDEX_FILE}
79+
MAIN_DEPENDENCY ${DOXYREST_CONFIG_OUT} ${DOXYREST_CONFIG_IN}
80+
COMMENT "Generating Doxyrest documentation"
81+
)
82+
# Target to generate rst from Doxygen XML using Doxyrest
83+
add_custom_target(
84+
Doxyrest
85+
ALL
86+
DEPENDS Doxygen ${DOXYREST_OUTPUT}
87+
)
88+
endfunction()
89+
90+
function(_setup_sphinx)
91+
set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
92+
set(SPHINX_OUTPUT_DIR ${DOC_OUTPUT_DIR}/docs)
93+
set(SPHINX_INDEX_FILE ${SPHINX_OUTPUT_DIR}/index.html)
94+
set(SPHINX_CONF_IN ${SPHINX_SOURCE}/conf.in)
95+
set(SPHINX_CONF_OUT ${SPHINX_SOURCE}/conf.py)
96+
# Only regenerate Sphinx when:
97+
# - Doxygen has rerun
98+
# - Our doc files have been updated
99+
# - The Sphinx config has been updated
100+
if(DPCTL_ENABLE_DOXYREST)
101+
add_custom_command(
102+
OUTPUT ${SPHINX_INDEX_FILE}
103+
COMMAND
104+
${SPHINX_EXECUTABLE} -b html
105+
${SPHINX_SOURCE}
106+
${SPHINX_OUTPUT_DIR}
107+
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
108+
DEPENDS
109+
# Other docs files that can be edited manually
110+
${CMAKE_CURRENT_SOURCE_DIR}/index.rst
111+
${DOXYGEN_INDEX_FILE}
112+
MAIN_DEPENDENCY ${SPHINX_CONF_OUT} ${SPHINX_CONF_IN}
113+
COMMENT "Generating Sphinx documentation"
114+
)
115+
# Target to generate Sphinx
116+
add_custom_target(
117+
Sphinx
118+
ALL
119+
DEPENDS Doxyrest ${SPHINX_INDEX_FILE}
120+
)
121+
else()
122+
configure_file(${INDEX_NO_DOXYREST_IN} ${INDEX_OUT} @ONLY)
123+
add_custom_command(
124+
OUTPUT ${SPHINX_INDEX_FILE}
125+
COMMAND
126+
${SPHINX_EXECUTABLE} -b html
127+
${SPHINX_SOURCE}
128+
${SPHINX_OUTPUT_DIR}
129+
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
130+
DEPENDS
131+
# Other docs files that can be edited manually
132+
${CMAKE_CURRENT_SOURCE_DIR}/index.rst
133+
MAIN_DEPENDENCY ${SPHINX_CONF_OUT} ${SPHINX_CONF_IN}
134+
COMMENT "Generating Sphinx documentation"
135+
)
136+
# Target to generate Sphinx
137+
add_custom_target(
138+
Sphinx
139+
ALL
140+
DEPENDS ${SPHINX_INDEX_FILE}
141+
)
142+
endif()
143+
# Create a conf.py by replacing variables inside @@ with the current values
144+
configure_file(${SPHINX_CONF_IN} ${SPHINX_CONF_OUT} @ONLY)
145+
endfunction()
146+
147+
function(_set_current_release)
148+
set(CURRENT_RELEASE "" PARENT_SCOPE)
149+
# Use git describe to get latest tag name
150+
if (GIT_FOUND)
151+
execute_process(
152+
COMMAND ${GIT_EXECUTABLE} describe --tags --abbrev=0
153+
RESULT_VARIABLE result
154+
OUTPUT_VARIABLE CURRENT_RELEASE
155+
OUTPUT_STRIP_TRAILING_WHITESPACE
156+
)
157+
set(CURRENT_COMMIT "")
158+
execute_process(
159+
COMMAND ${GIT_EXECUTABLE} describe --tags
160+
RESULT_VARIABLE result
161+
OUTPUT_VARIABLE CURRENT_COMMIT
162+
OUTPUT_STRIP_TRAILING_WHITESPACE
163+
)
164+
if (NOT "${CURRENT_RELEASE}" STREQUAL "${CURRENT_COMMIT}")
165+
set(CURRENT_RELEASE "master")
166+
endif ()
167+
set(CURRENT_RELEASE ${CURRENT_RELEASE} PARENT_SCOPE)
168+
endif (GIT_FOUND)
169+
endfunction()
170+
171+
##----------------------------------------------------------------------------##
172+
3173
# Add the cmake folder so the FindSphinx module is found
4174
set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake" ${CMAKE_MODULE_PATH})
5-
175+
find_package(Git)
6176
find_package(Sphinx REQUIRED)
7177
find_package(Doxygen REQUIRED)
8-
find_package (Git)
178+
if (DPCTL_ENABLE_DOXYREST)
179+
find_package(Lua REQUIRED)
180+
find_package(Doxyrest REQUIRED)
181+
endif()
9182

10-
set(DOC_OUTPUT_DIR ${CMAKE_CURRENT_SOURCE_DIR}/generated_docs)
11-
if( DPCTL_DOCGEN_PREFIX )
183+
# Set the location where the generated docs are saved
184+
if(DPCTL_DOCGEN_PREFIX)
12185
message(STATUS "Generating dpctl documents in " ${DPCTL_DOCGEN_PREFIX})
13186
set(DOC_OUTPUT_DIR ${DPCTL_DOCGEN_PREFIX})
187+
else()
188+
set(DOC_OUTPUT_DIR ${CMAKE_CURRENT_SOURCE_DIR}/generated_docs)
14189
endif()
15190

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-
set(CURRENT_COMMIT "")
27-
execute_process(
28-
COMMAND ${GIT_EXECUTABLE} describe --tags
29-
RESULT_VARIABLE result
30-
OUTPUT_VARIABLE CURRENT_COMMIT
31-
OUTPUT_STRIP_TRAILING_WHITESPACE
32-
)
33-
if (NOT "${CURRENT_RELEASE}" STREQUAL "${CURRENT_COMMIT}")
34-
set(CURRENT_RELEASE "master")
35-
endif ()
36-
endif (GIT_FOUND)
37-
38-
set(DOXYGEN_INPUT_DIR ../dpctl-capi)
39-
set(DOXYGEN_OUTPUT_DIR ${DOC_OUTPUT_DIR}/doxygen)
40-
set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/html/index.html)
41-
set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
42-
set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
43-
44-
# Replace variables inside @@ with the current values
45-
configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
46-
47-
file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})
48-
49-
add_custom_command(
50-
OUTPUT ${DOXYGEN_INDEX_FILE}
51-
DEPENDS ${DPCTL_PUBLIC_HEADERS}
52-
COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
53-
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
54-
MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
55-
COMMENT "Generating Doxygen documentation"
56-
VERBATIM
57-
)
58-
59-
set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
60-
set(SPHINX_OUTPUT_DIR ${DOC_OUTPUT_DIR}/docs)
61-
set(SPHINX_INDEX_FILE ${SPHINX_OUTPUT_DIR}/index.html)
62-
set(SPHINX_CONF_IN ${SPHINX_SOURCE}/conf.in)
63-
set(SPHINX_CONF_OUT ${SPHINX_SOURCE}/conf.py)
64-
65-
# Create a conf.py by replacing variables inside @@ with the current values
66-
configure_file(${SPHINX_CONF_IN} ${SPHINX_CONF_OUT} @ONLY)
67-
68-
# Only regenerate Sphinx when:
69-
# - Doxygen has rerun
70-
# - Our doc files have been updated
71-
# - The Sphinx config has been updated
72-
add_custom_command(
73-
OUTPUT ${SPHINX_INDEX_FILE}
74-
COMMAND
75-
${SPHINX_EXECUTABLE} -b html
76-
# Tell Breathe where to find the Doxygen output
77-
-Dbreathe_projects.dpctl-CAPI=${DOXYGEN_OUTPUT_DIR}/xml
78-
${SPHINX_SOURCE} ${SPHINX_OUTPUT_DIR}
79-
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
80-
DEPENDS
81-
# Other docs files that can be edited manually
82-
${CMAKE_CURRENT_SOURCE_DIR}/index.rst
83-
${DOXYGEN_INDEX_FILE}
84-
MAIN_DEPENDENCY ${SPHINX_CONF_OUT} ${SPHINX_CONF_IN}
85-
COMMENT "Generating Sphinx documentation"
86-
)
87-
88-
# Target to generate only Doxygen documentation
89-
add_custom_target(
90-
Doxygen
91-
ALL
92-
DEPENDS ${DOXYGEN_INDEX_FILE}
93-
)
191+
set(INDEX_NO_DOXYREST_IN ${CMAKE_CURRENT_SOURCE_DIR}/index_no_doxyrest.rst.in)
192+
set(INDEX_DOXYREST_IN ${CMAKE_CURRENT_SOURCE_DIR}/index_doxyrest.rst.in)
193+
set(INDEX_OUT ${CMAKE_CURRENT_SOURCE_DIR}/index.rst)
94194

95-
# Target to generate all documentation Sphinx and Doxygen
96-
add_custom_target(
97-
Sphinx
98-
ALL
99-
DEPENDS Doxygen ${SPHINX_INDEX_FILE}
100-
)
195+
_set_current_release()
196+
_setup_doxygen()
197+
if(DPCTL_ENABLE_DOXYREST)
198+
_setup_doxyrest()
199+
endif()
200+
_setup_sphinx()

‎docs/Doxyfile.in

+9-7
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ PROJECT_NUMBER = @CURRENT_RELEASE@
4444
# for a project that appears at the top of each page and should give viewer a
4545
# quick idea about the purpose of the project. Keep the description short.
4646

47-
PROJECT_BRIEF = "A SYCL queue and memory manager for Python modules."
47+
PROJECT_BRIEF = "A lightweight C API for SYCL runtime classes"
4848

4949
# With the PROJECT_LOGO tag one can specify a logo or an icon that is included
5050
# in the documentation. The maximum height of the logo should not exceed 55
@@ -917,9 +917,11 @@ RECURSIVE = YES
917917
# Note that relative paths are relative to the directory from which doxygen is
918918
# run.
919919

920-
EXCLUDE = ../dpctl-capi/build
921-
EXCLUDE += ../dpctl-capi/install
922-
EXCLUDE += ../dpctl-capi/tests
920+
EXCLUDE = ../dpctl-capi/include/Support
921+
EXCLUDE += ../dpctl-capi/include/Config
922+
EXCLUDE += ../dpctl-capi/include/dpctl_vector.h
923+
EXCLUDE += ../dpctl-capi/include/dpctl_data_types.h
924+
EXCLUDE += ../dpctl-capi/include/dpctl_utils.h
923925

924926
# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
925927
# directories that are symbolic links (a Unix file system feature) are excluded
@@ -2161,15 +2163,15 @@ ENABLE_PREPROCESSING = YES
21612163
# The default value is: NO.
21622164
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
21632165

2164-
MACRO_EXPANSION = NO
2166+
MACRO_EXPANSION = YES
21652167

21662168
# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
21672169
# the macro expansion is limited to the macros specified with the PREDEFINED and
21682170
# EXPAND_AS_DEFINED tags.
21692171
# The default value is: NO.
21702172
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
21712173

2172-
EXPAND_ONLY_PREDEF = NO
2174+
EXPAND_ONLY_PREDEF = YES
21732175

21742176
# If the SEARCH_INCLUDES tag is set to YES, the include files in the
21752177
# INCLUDE_PATH will be searched if a #include is found.
@@ -2210,7 +2212,7 @@ PREDEFINED =
22102212
# definition found in the source code.
22112213
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
22122214

2213-
EXPAND_AS_DEFINED =
2215+
EXPAND_AS_DEFINED = DPCTL_DECLARE_VECTOR
22142216

22152217
# If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will
22162218
# remove all references to function-like macros that are alone on a line, have

0 commit comments

Comments
 (0)