Skip to content

Commit 45eccf9

Browse files
author
Diptorup Deb
committed
Improvements to documentation build system.
 - Move to doxyrest for generating rest from doxygen - Rewrite CMakeLists to support generating docs with and without C API doc generation. - Minor changes to docstrings.
1 parent 9a5f21d commit 45eccf9

20 files changed

+812
-158
lines changed

‎docs/.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
docs
22
generated_docs
3+
dpctl-capi-doxyrest
34
api
45
build
56
conf.py
7+
index.rst
8+
doxyrest-config.lua

‎docs/CMakeLists.txt

Lines changed: 171 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -1,100 +1,188 @@
11
cmake_minimum_required(VERSION 3.18 FATAL_ERROR)
22
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})
53

6-
find_package(Sphinx REQUIRED)
7-
find_package(Doxygen REQUIRED)
8-
find_package (Git)
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+
)
99

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()
10+
# This function defines everything needed to generate Doxygen docs
11+
function(_setup_doxygen)
12+
# We generate doxygen only for the public headers to keep the Doxyrest
13+
# generated rst files clean.
14+
# FIXME: make it possible to generate doxygen for all files.
15+
set(DOXYGEN_INPUT_DIR ../dpctl-capi/include)
16+
set(DOXYGEN_OUTPUT_DIR ${DOC_OUTPUT_DIR}/doxygen)
17+
set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/xml/index.xml)
18+
set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
19+
set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
20+
21+
# Populate the configurable values in the Doxyfile.in and
22+
# generate the actual Doxyfile.
23+
configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
1524

16-
set(CURRENT_RELEASE "")
25+
file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})
1726

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
27+
# Custom command to run Doxygen
28+
add_custom_command(
29+
OUTPUT ${DOXYGEN_INDEX_FILE}
30+
DEPENDS ${DPCTL_PUBLIC_HEADERS}
31+
COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
32+
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
33+
MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
34+
COMMENT "Generating Doxygen documentation"
35+
VERBATIM
2536
)
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
37+
38+
# Target to generate only Doxygen documentation
39+
add_custom_target(
40+
Doxygen
41+
ALL
42+
DEPENDS ${DOXYGEN_INDEX_FILE}
3243
)
33-
if (NOT "${CURRENT_RELEASE}" STREQUAL "${CURRENT_COMMIT}")
34-
set(CURRENT_RELEASE "master")
35-
endif ()
36-
endif (GIT_FOUND)
44+
endfunction()
3745

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)
46+
function(_setup_doxyrest)
47+
set(DOXYREST_OUTPUT_DIR_NAME dpctl-capi-doxyrest)
48+
set(DOXYREST_OUTPUT_DIR
49+
${CMAKE_CURRENT_SOURCE_DIR}/${DOXYREST_OUTPUT_DIR_NAME}
50+
)
51+
set(DOXYREST_CONFIG_IN ${CMAKE_CURRENT_SOURCE_DIR}/doxyrest-config.lua.in)
52+
set(DOXYREST_CONFIG_OUT ${CMAKE_CURRENT_SOURCE_DIR}/doxyrest-config.lua)
53+
set(DOXYREST_OUTPUT ${DOXYREST_OUTPUT_DIR}/index.rst)
54+
set(DOXYGEN_OUTPUT_DIR ${DOC_OUTPUT_DIR}/doxygen)
55+
configure_file(${DOXYREST_CONFIG_IN} ${DOXYREST_CONFIG_OUT} @ONLY)
56+
configure_file(${INDEX_DOXYREST_IN} ${INDEX_OUT} @ONLY)
57+
add_custom_command(
58+
OUTPUT ${DOXYREST_OUTPUT}
59+
COMMAND
60+
${DOXYREST_EXE} -c
61+
${DOXYREST_CONFIG_OUT}
62+
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
63+
DEPENDS
64+
# Other docs files that can be edited manually
65+
${INDEX_OUT}
66+
${DOXYGEN_INDEX_FILE}
67+
MAIN_DEPENDENCY ${DOXYREST_CONFIG_OUT} ${DOXYREST_CONFIG_IN}
68+
COMMENT "Generating Doxyrest documentation"
69+
)
70+
# Target to generate rst from Doxygen XML using Doxyrest
71+
add_custom_target(
72+
Doxyrest
73+
ALL
74+
DEPENDS Doxygen ${DOXYREST_OUTPUT}
75+
)
76+
endfunction()
4377

44-
# Replace variables inside @@ with the current values
45-
configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
78+
function(_setup_sphinx)
79+
set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
80+
set(SPHINX_OUTPUT_DIR ${DOC_OUTPUT_DIR}/docs)
81+
set(SPHINX_INDEX_FILE ${SPHINX_OUTPUT_DIR}/index.html)
82+
set(SPHINX_CONF_IN ${SPHINX_SOURCE}/conf.in)
83+
set(SPHINX_CONF_OUT ${SPHINX_SOURCE}/conf.py)
4684

47-
file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})
85+
# Only regenerate Sphinx when:
86+
# - Doxygen has rerun
87+
# - Our doc files have been updated
88+
# - The Sphinx config has been updated
89+
if(DPCTL_ENABLE_DOXYREST)
90+
add_custom_command(
91+
OUTPUT ${SPHINX_INDEX_FILE}
92+
COMMAND
93+
${SPHINX_EXECUTABLE} -b html
94+
${SPHINX_SOURCE}
95+
${SPHINX_OUTPUT_DIR}
96+
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
97+
DEPENDS
98+
# Other docs files that can be edited manually
99+
${CMAKE_CURRENT_SOURCE_DIR}/index.rst
100+
${DOXYGEN_INDEX_FILE}
101+
MAIN_DEPENDENCY ${SPHINX_CONF_OUT} ${SPHINX_CONF_IN}
102+
COMMENT "Generating Sphinx documentation"
103+
)
104+
# Target to generate Sphinx
105+
add_custom_target(
106+
Sphinx
107+
ALL
108+
DEPENDS Doxyrest ${SPHINX_INDEX_FILE}
109+
)
110+
else()
111+
configure_file(${INDEX_NO_DOXYREST_IN} ${INDEX_OUT} @ONLY)
112+
add_custom_command(
113+
OUTPUT ${SPHINX_INDEX_FILE}
114+
COMMAND
115+
${SPHINX_EXECUTABLE} -b html
116+
${SPHINX_SOURCE}
117+
${SPHINX_OUTPUT_DIR}
118+
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
119+
DEPENDS
120+
# Other docs files that can be edited manually
121+
${CMAKE_CURRENT_SOURCE_DIR}/index.rst
122+
MAIN_DEPENDENCY ${SPHINX_CONF_OUT} ${SPHINX_CONF_IN}
123+
COMMENT "Generating Sphinx documentation"
124+
)
125+
# Target to generate Sphinx
126+
add_custom_target(
127+
Sphinx
128+
ALL
129+
DEPENDS ${SPHINX_INDEX_FILE}
130+
)
131+
endif()
132+
# Create a conf.py by replacing variables inside @@ with the current values
133+
configure_file(${SPHINX_CONF_IN} ${SPHINX_CONF_OUT} @ONLY)
134+
endfunction()
48135

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-
)
136+
function(_set_current_release)
137+
set(CURRENT_RELEASE "")
138+
# Use git describe to get latest tag name
139+
if (GIT_FOUND)
140+
execute_process(
141+
COMMAND ${GIT_EXECUTABLE} describe --tags --abbrev=0
142+
RESULT_VARIABLE result
143+
OUTPUT_VARIABLE CURRENT_RELEASE
144+
OUTPUT_STRIP_TRAILING_WHITESPACE
145+
)
146+
set(CURRENT_COMMIT "")
147+
execute_process(
148+
COMMAND ${GIT_EXECUTABLE} describe --tags
149+
RESULT_VARIABLE result
150+
OUTPUT_VARIABLE CURRENT_COMMIT
151+
OUTPUT_STRIP_TRAILING_WHITESPACE
152+
)
153+
if (NOT "${CURRENT_RELEASE}" STREQUAL "${CURRENT_COMMIT}")
154+
set(CURRENT_RELEASE "master")
155+
endif ()
156+
endif (GIT_FOUND)
157+
endfunction()
58158

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)
159+
##----------------------------------------------------------------------------##
64160

65-
# Create a conf.py by replacing variables inside @@ with the current values
66-
configure_file(${SPHINX_CONF_IN} ${SPHINX_CONF_OUT} @ONLY)
161+
# Add the cmake folder so the FindSphinx module is found
162+
set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake" ${CMAKE_MODULE_PATH})
163+
find_package(Git)
164+
find_package(Sphinx REQUIRED)
165+
find_package(Doxygen REQUIRED)
166+
if (DPCTL_ENABLE_DOXYREST)
167+
find_package(Lua REQUIRED)
168+
find_package(Doxyrest REQUIRED)
169+
endif()
67170

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-
)
171+
# Set the location where the generated docs are saved
172+
if(DPCTL_DOCGEN_PREFIX)
173+
message(STATUS "Generating dpctl documents in " ${DPCTL_DOCGEN_PREFIX})
174+
set(DOC_OUTPUT_DIR ${DPCTL_DOCGEN_PREFIX})
175+
else()
176+
set(DOC_OUTPUT_DIR ${CMAKE_CURRENT_SOURCE_DIR}/generated_docs)
177+
endif()
87178

88-
# Target to generate only Doxygen documentation
89-
add_custom_target(
90-
Doxygen
91-
ALL
92-
DEPENDS ${DOXYGEN_INDEX_FILE}
93-
)
179+
set(INDEX_NO_DOXYREST_IN ${CMAKE_CURRENT_SOURCE_DIR}/index_no_doxyrest.rst.in)
180+
set(INDEX_DOXYREST_IN ${CMAKE_CURRENT_SOURCE_DIR}/index_doxyrest.rst.in)
181+
set(INDEX_OUT ${CMAKE_CURRENT_SOURCE_DIR}/index.rst)
94182

95-
# Target to generate all documentation Sphinx and Doxygen
96-
add_custom_target(
97-
Sphinx
98-
ALL
99-
DEPENDS Doxygen ${SPHINX_INDEX_FILE}
100-
)
183+
_set_current_release()
184+
_setup_doxygen()
185+
if(DPCTL_ENABLE_DOXYREST)
186+
_setup_doxyrest()
187+
endif()
188+
_setup_sphinx()

‎docs/Doxyfile.in

Lines changed: 2 additions & 5 deletions
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,10 +917,7 @@ 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
923-
EXCLUDE += ../dpctl-capi/CMakeLists.txt
920+
EXCLUDE =
924921

925922
# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
926923
# directories that are symbolic links (a Unix file system feature) are excluded

0 commit comments

Comments
 (0)