Skip to content

Commit 08e3336

Browse files
author
Diptorup Deb
committed
Use doxyrest to generate C API documentation.
 - Remove breathe and exhale requirements and instead use Doxyrest for the C API documentation. - Add cmake changes related to Doxyrest. - Provide two separate modes of documentation generation: both C and Python API and only Python API. - Update README, gitignore.
1 parent a0573b0 commit 08e3336

File tree

10 files changed

+810
-145
lines changed

10 files changed

+810
-145
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+
docfiles/dpctl-capi
34
api
45
build
56
conf.py
7+
index.rst
8+
doxyrest-config.lua

‎docs/CMakeLists.txt

Lines changed: 176 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -1,100 +1,193 @@
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 docfiles/dpctl-capi)
48+
set(DOXYREST_OUTPUT_DIR
49+
${CMAKE_CURRENT_SOURCE_DIR}/${DOXYREST_OUTPUT_DIR_NAME}
50+
PARENT_SCOPE
51+
)
52+
set(DOXYREST_OUTPUT_DIR
53+
${CMAKE_CURRENT_SOURCE_DIR}/${DOXYREST_OUTPUT_DIR_NAME}
4354

44-
# Replace variables inside @@ with the current values
45-
configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
55+
)
56+
set(DOXYREST_CONFIG_IN ${CMAKE_CURRENT_SOURCE_DIR}/doxyrest-config.lua.in)
57+
set(DOXYREST_CONFIG_OUT ${CMAKE_CURRENT_SOURCE_DIR}/doxyrest-config.lua)
58+
set(DOXYREST_OUTPUT ${DOXYREST_OUTPUT_DIR}/index.rst)
59+
set(DOXYGEN_OUTPUT_DIR ${DOC_OUTPUT_DIR}/doxygen)
60+
configure_file(${DOXYREST_CONFIG_IN} ${DOXYREST_CONFIG_OUT} @ONLY)
61+
configure_file(${INDEX_DOXYREST_IN} ${INDEX_OUT} @ONLY)
62+
add_custom_command(
63+
OUTPUT ${DOXYREST_OUTPUT}
64+
COMMAND
65+
${DOXYREST_EXE} -c
66+
${DOXYREST_CONFIG_OUT}
67+
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
68+
DEPENDS
69+
# Other docs files that can be edited manually
70+
${INDEX_OUT}
71+
${DOXYGEN_INDEX_FILE}
72+
MAIN_DEPENDENCY ${DOXYREST_CONFIG_OUT} ${DOXYREST_CONFIG_IN}
73+
COMMENT "Generating Doxyrest documentation"
74+
)
75+
# Target to generate rst from Doxygen XML using Doxyrest
76+
add_custom_target(
77+
Doxyrest
78+
ALL
79+
DEPENDS Doxygen ${DOXYREST_OUTPUT}
80+
)
81+
endfunction()
4682

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

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

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)
164+
##----------------------------------------------------------------------------##
64165

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

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-
)
176+
# Set the location where the generated docs are saved
177+
if(DPCTL_DOCGEN_PREFIX)
178+
message(STATUS "Generating dpctl documents in " ${DPCTL_DOCGEN_PREFIX})
179+
set(DOC_OUTPUT_DIR ${DPCTL_DOCGEN_PREFIX})
180+
else()
181+
set(DOC_OUTPUT_DIR ${CMAKE_CURRENT_SOURCE_DIR}/generated_docs)
182+
endif()
87183

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

95-
# Target to generate all documentation Sphinx and Doxygen
96-
add_custom_target(
97-
Sphinx
98-
ALL
99-
DEPENDS Doxygen ${SPHINX_INDEX_FILE}
100-
)
188+
_set_current_release()
189+
_setup_doxygen()
190+
if(DPCTL_ENABLE_DOXYREST)
191+
_setup_doxyrest()
192+
endif()
193+
_setup_sphinx()

‎docs/README.md

Lines changed: 77 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,89 @@
11
What?
22
=====
33

4-
Generator scripts for dpctl API documentation. To run these scripts, follow
5-
the following steps:
4+
This README provides the steps to generate the documentation for both the
5+
C and Python API of dpctl. The documentation of dpctl can be generated either
6+
as a set of consolidated HTML pages containing both Python and C API, or
7+
separate set of pages for C API and Python API. It is suggested that the
8+
consolidated documentation is generated using the provided build scripts.
9+
10+
Prerequisite
11+
============
12+
13+
The following tools are needed in order to build the documentation for dpctl
14+
15+
- `Sphinx`
16+
- `Doxygen`
17+
- `Doxyrest` [optional]
18+
- `Lua` [optional]
19+
20+
`Doxyrest` and `Lua` are needed to generate `rst` files from the `Doxygen`
21+
output and add them to a consolidate `Sphinx` generated site. It is preferred
22+
that the latest `Doxyrest` binary is installed from
23+
https://github.com/vovkos/doxyrest/tags.
24+
25+
`Lua` is required if using `Doxyrest`. Please follow your OS specific
26+
instructions to install `liblua`. *E.g.*, on Ubuntu 20.04:
27+
28+
```
29+
sudo apt-get install liblua5.2-dev
30+
```
31+
32+
Generating the docs
33+
===================
34+
35+
The documentation should be generated using the provided `Cmake` build script.
36+
There are a few configurable options that can be used to select the type of
37+
documentation to generate.
38+
39+
Build only Doxygen for C API
40+
----------------------------
641
```bash
742
cd dpctl/docs
8-
mkdir build
43+
mkdir -p build
944
cd build
10-
cmake -DDPCTL_DOCGEN_PREFIX=<WHERE_YOU_WANT_DOCS_TO_BE_GENERATED> ..
11-
make Sphinx
45+
cmake ..
46+
make Doxygen
1247
```
48+
The above steps will generate the `Doxygen` files at
49+
`dpctl/docs/generated_docs/doxygen/html`. The documentation can also be
50+
generated at a custom location by providing the optional flag
1351

14-
The `DPCTL_DOCGEN_PREFIX` flag is optional and can be omitted to generate the
15-
documents in the current source directory in a sub-directory called
16-
`generated_docs`.
52+
```bash
53+
cd dpctl/docs
54+
mkdir -p build
55+
cd build
56+
cmake .. -DDPCTL_DOCGEN_PREFIX=<WHERE_YOU_WANT_DOCS_TO_BE_GENERATED>
57+
make Doxygen
58+
```
1759

18-
The `make Sphinx` command will generate standalone Doxygen documentation and
19-
a consolidated Sphinx documentation for both dpctl Python and C APIs.
60+
Build only Sphinx for Python API
61+
--------------------------------
62+
```bash
63+
cd dpctl/docs
64+
mkdir -p build
65+
cd build
66+
cmake .. -DDPCTL_DOCGEN_PREFIX=<WHERE_YOU_WANT_DOCS_TO_BE_GENERATED>
67+
make Sphinx
68+
```
2069

21-
Prerequisite
22-
============
70+
The `make Sphinx` command will generate only the Python API docs for dpctl.
2371

24-
Before you generate the documentation make sure you have the following
25-
packages installed:
72+
Build consolidated docs
73+
-----------------------
74+
It is possible to generate a single site with both Python and C API docs. As
75+
mentioned before, `Doxyrest` and `Lua` are required to generate the consolidated
76+
site.
2677

27-
- sphinx
28-
- doxygen
29-
- breathe
30-
- exhale
78+
```bash
79+
cd dpctl/docs
80+
mkdir -p build
81+
cd build
82+
cmake .. \
83+
-DDPCTL_ENABLE_DOXYREST=ON \
84+
-DDoxyrest_DIR=<PATH_TO_DOXYREST_INSTALL_DIR> \
85+
-DDPCTL_DOCGEN_PREFIX=<WHERE_YOU_WANT_DOCS_TO_BE_GENERATED>
86+
make Sphinx
87+
```
88+
The `Doxyrest_DIR` flag is optional, but is needed when Doxyrest is installed in
89+
a non-system location.

0 commit comments

Comments
 (0)