Skip to content

Commit

Permalink
Merge pull request #397 from diptorupd/feature/doc-infra-improvements
Browse files Browse the repository at this point in the history 
Feature/documentation infrastructure improvements
  • Loading branch information
Diptorup Deb authored Apr 19, 2021
2 parents 82eed52 + 0d61611 commit f5cd7c7
Show file tree
Hide file tree
Showing 28 changed files with 1,503 additions and 258 deletions.
3 changes: 3 additions & 0 deletions docs/.gitignore
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
docs
generated_docs
docfiles/dpctl-capi
api
build
conf.py
index.rst
doxyrest-config.lua
276 changes: 188 additions & 88 deletions docs/CMakeLists.txt
View file
Original file line number Diff line number Diff line change
@@ -1,100 +1,200 @@
cmake_minimum_required(VERSION 3.18 FATAL_ERROR)
project("Data-parallel Control (dpctl)")

# Option to generate rst for C API and add to Sphinx documentation
option(DPCTL_ENABLE_DOXYREST
"Enable generation of rst files for C API"
OFF
)

# Option to add verion links to the side bar. This option is primarily
# intended to generate dpctl's docs for our github.io page.
option(DPCTL_USE_MULTIVERSION_TEMPLATE
"Enable adding verion links to side bar"
OFF
)

# This function defines everything needed to generate Doxygen docs
function(_setup_doxygen)
# We generate doxygen only for the public headers to keep the Doxyrest
# generated rst files clean.
# FIXME: make it possible to generate doxygen for all files.
set(DOXYGEN_INPUT_DIR ../dpctl-capi/include)
set(DOXYGEN_OUTPUT_DIR ${DOC_OUTPUT_DIR}/doxygen)
set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/xml/index.xml)
set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)

# Populate the configurable values in the Doxyfile.in and
# generate the actual Doxyfile.
configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)

file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})

# Custom command to run Doxygen
add_custom_command(
OUTPUT ${DOXYGEN_INDEX_FILE}
DEPENDS ${DPCTL_PUBLIC_HEADERS}
COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
COMMENT "Generating Doxygen documentation"
VERBATIM
)

# Target to generate only Doxygen documentation
add_custom_target(
Doxygen
ALL
DEPENDS ${DOXYGEN_INDEX_FILE}
)
endfunction()

function(_setup_doxyrest)
set(DOXYREST_OUTPUT_DIR_NAME docfiles/dpctl-capi)
set(DOXYREST_OUTPUT_DIR
${CMAKE_CURRENT_SOURCE_DIR}/${DOXYREST_OUTPUT_DIR_NAME}
PARENT_SCOPE
)
set(DOXYREST_OUTPUT_DIR
${CMAKE_CURRENT_SOURCE_DIR}/${DOXYREST_OUTPUT_DIR_NAME}

)
set(DOXYREST_CONFIG_IN ${CMAKE_CURRENT_SOURCE_DIR}/doxyrest-config.lua.in)
set(DOXYREST_CONFIG_OUT ${CMAKE_CURRENT_SOURCE_DIR}/doxyrest-config.lua)
set(DOXYREST_OUTPUT ${DOXYREST_OUTPUT_DIR}/index.rst)
set(DOXYGEN_OUTPUT_DIR ${DOC_OUTPUT_DIR}/doxygen)
configure_file(${DOXYREST_CONFIG_IN} ${DOXYREST_CONFIG_OUT} @ONLY)
configure_file(${INDEX_DOXYREST_IN} ${INDEX_OUT} @ONLY)
add_custom_command(
OUTPUT ${DOXYREST_OUTPUT}
COMMAND
${DOXYREST_EXE} -c
${DOXYREST_CONFIG_OUT}
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
DEPENDS
# Other docs files that can be edited manually
${INDEX_OUT}
${DOXYGEN_INDEX_FILE}
MAIN_DEPENDENCY ${DOXYREST_CONFIG_OUT} ${DOXYREST_CONFIG_IN}
COMMENT "Generating Doxyrest documentation"
)
# Target to generate rst from Doxygen XML using Doxyrest
add_custom_target(
Doxyrest
ALL
DEPENDS Doxygen ${DOXYREST_OUTPUT}
)
endfunction()

function(_setup_sphinx)
set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
set(SPHINX_OUTPUT_DIR ${DOC_OUTPUT_DIR}/docs)
set(SPHINX_INDEX_FILE ${SPHINX_OUTPUT_DIR}/index.html)
set(SPHINX_CONF_IN ${SPHINX_SOURCE}/conf.in)
set(SPHINX_CONF_OUT ${SPHINX_SOURCE}/conf.py)
# Only regenerate Sphinx when:
# - Doxygen has rerun
# - Our doc files have been updated
# - The Sphinx config has been updated
if(DPCTL_ENABLE_DOXYREST)
add_custom_command(
OUTPUT ${SPHINX_INDEX_FILE}
COMMAND
${SPHINX_EXECUTABLE} -b html
${SPHINX_SOURCE}
${SPHINX_OUTPUT_DIR}
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
DEPENDS
# Other docs files that can be edited manually
${CMAKE_CURRENT_SOURCE_DIR}/index.rst
${DOXYGEN_INDEX_FILE}
MAIN_DEPENDENCY ${SPHINX_CONF_OUT} ${SPHINX_CONF_IN}
COMMENT "Generating Sphinx documentation"
)
# Target to generate Sphinx
add_custom_target(
Sphinx
ALL
DEPENDS Doxyrest ${SPHINX_INDEX_FILE}
)
else()
configure_file(${INDEX_NO_DOXYREST_IN} ${INDEX_OUT} @ONLY)
add_custom_command(
OUTPUT ${SPHINX_INDEX_FILE}
COMMAND
${SPHINX_EXECUTABLE} -b html
${SPHINX_SOURCE}
${SPHINX_OUTPUT_DIR}
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
DEPENDS
# Other docs files that can be edited manually
${CMAKE_CURRENT_SOURCE_DIR}/index.rst
MAIN_DEPENDENCY ${SPHINX_CONF_OUT} ${SPHINX_CONF_IN}
COMMENT "Generating Sphinx documentation"
)
# Target to generate Sphinx
add_custom_target(
Sphinx
ALL
DEPENDS ${SPHINX_INDEX_FILE}
)
endif()
# Create a conf.py by replacing variables inside @@ with the current values
configure_file(${SPHINX_CONF_IN} ${SPHINX_CONF_OUT} @ONLY)
endfunction()

function(_set_current_release)
set(CURRENT_RELEASE "" PARENT_SCOPE)
# Use git describe to get latest tag name
if (GIT_FOUND)
execute_process(
COMMAND ${GIT_EXECUTABLE} describe --tags --abbrev=0
RESULT_VARIABLE result
OUTPUT_VARIABLE CURRENT_RELEASE
OUTPUT_STRIP_TRAILING_WHITESPACE
)
set(CURRENT_COMMIT "")
execute_process(
COMMAND ${GIT_EXECUTABLE} describe --tags
RESULT_VARIABLE result
OUTPUT_VARIABLE CURRENT_COMMIT
OUTPUT_STRIP_TRAILING_WHITESPACE
)
if (NOT "${CURRENT_RELEASE}" STREQUAL "${CURRENT_COMMIT}")
set(CURRENT_RELEASE "master")
endif ()
set(CURRENT_RELEASE ${CURRENT_RELEASE} PARENT_SCOPE)
endif (GIT_FOUND)
endfunction()

##----------------------------------------------------------------------------##

# Add the cmake folder so the FindSphinx module is found
set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake" ${CMAKE_MODULE_PATH})

find_package(Git)
find_package(Sphinx REQUIRED)
find_package(Doxygen REQUIRED)
find_package (Git)
if (DPCTL_ENABLE_DOXYREST)
find_package(Lua REQUIRED)
find_package(Doxyrest REQUIRED)
endif()

set(DOC_OUTPUT_DIR ${CMAKE_CURRENT_SOURCE_DIR}/generated_docs)
if( DPCTL_DOCGEN_PREFIX )
# Set the location where the generated docs are saved
if(DPCTL_DOCGEN_PREFIX)
message(STATUS "Generating dpctl documents in " ${DPCTL_DOCGEN_PREFIX})
set(DOC_OUTPUT_DIR ${DPCTL_DOCGEN_PREFIX})
else()
set(DOC_OUTPUT_DIR ${CMAKE_CURRENT_SOURCE_DIR}/generated_docs)
endif()

set(CURRENT_RELEASE "")

# Use git describe to get latest tag name
if (GIT_FOUND)
execute_process(
COMMAND ${GIT_EXECUTABLE} describe --tags --abbrev=0
RESULT_VARIABLE result
OUTPUT_VARIABLE CURRENT_RELEASE
OUTPUT_STRIP_TRAILING_WHITESPACE
)
set(CURRENT_COMMIT "")
execute_process(
COMMAND ${GIT_EXECUTABLE} describe --tags
RESULT_VARIABLE result
OUTPUT_VARIABLE CURRENT_COMMIT
OUTPUT_STRIP_TRAILING_WHITESPACE
)
if (NOT "${CURRENT_RELEASE}" STREQUAL "${CURRENT_COMMIT}")
set(CURRENT_RELEASE "master")
endif ()
endif (GIT_FOUND)

set(DOXYGEN_INPUT_DIR ../dpctl-capi)
set(DOXYGEN_OUTPUT_DIR ${DOC_OUTPUT_DIR}/doxygen)
set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/html/index.html)
set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)

# Replace variables inside @@ with the current values
configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)

file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})

add_custom_command(
OUTPUT ${DOXYGEN_INDEX_FILE}
DEPENDS ${DPCTL_PUBLIC_HEADERS}
COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
COMMENT "Generating Doxygen documentation"
VERBATIM
)

set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
set(SPHINX_OUTPUT_DIR ${DOC_OUTPUT_DIR}/docs)
set(SPHINX_INDEX_FILE ${SPHINX_OUTPUT_DIR}/index.html)
set(SPHINX_CONF_IN ${SPHINX_SOURCE}/conf.in)
set(SPHINX_CONF_OUT ${SPHINX_SOURCE}/conf.py)

# Create a conf.py by replacing variables inside @@ with the current values
configure_file(${SPHINX_CONF_IN} ${SPHINX_CONF_OUT} @ONLY)

# Only regenerate Sphinx when:
# - Doxygen has rerun
# - Our doc files have been updated
# - The Sphinx config has been updated
add_custom_command(
OUTPUT ${SPHINX_INDEX_FILE}
COMMAND
${SPHINX_EXECUTABLE} -b html
# Tell Breathe where to find the Doxygen output
-Dbreathe_projects.dpctl-CAPI=${DOXYGEN_OUTPUT_DIR}/xml
${SPHINX_SOURCE} ${SPHINX_OUTPUT_DIR}
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
DEPENDS
# Other docs files that can be edited manually
${CMAKE_CURRENT_SOURCE_DIR}/index.rst
${DOXYGEN_INDEX_FILE}
MAIN_DEPENDENCY ${SPHINX_CONF_OUT} ${SPHINX_CONF_IN}
COMMENT "Generating Sphinx documentation"
)

# Target to generate only Doxygen documentation
add_custom_target(
Doxygen
ALL
DEPENDS ${DOXYGEN_INDEX_FILE}
)
set(INDEX_NO_DOXYREST_IN ${CMAKE_CURRENT_SOURCE_DIR}/index_no_doxyrest.rst.in)
set(INDEX_DOXYREST_IN ${CMAKE_CURRENT_SOURCE_DIR}/index_doxyrest.rst.in)
set(INDEX_OUT ${CMAKE_CURRENT_SOURCE_DIR}/index.rst)

# Target to generate all documentation Sphinx and Doxygen
add_custom_target(
Sphinx
ALL
DEPENDS Doxygen ${SPHINX_INDEX_FILE}
)
_set_current_release()
_setup_doxygen()
if(DPCTL_ENABLE_DOXYREST)
_setup_doxyrest()
endif()
_setup_sphinx()
16 changes: 9 additions & 7 deletions docs/Doxyfile.in
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ PROJECT_NUMBER = @CURRENT_RELEASE@
# for a project that appears at the top of each page and should give viewer a
# quick idea about the purpose of the project. Keep the description short.

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

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

EXCLUDE = ../dpctl-capi/build
EXCLUDE += ../dpctl-capi/install
EXCLUDE += ../dpctl-capi/tests
EXCLUDE = ../dpctl-capi/include/Support
EXCLUDE += ../dpctl-capi/include/Config
EXCLUDE += ../dpctl-capi/include/dpctl_vector.h
EXCLUDE += ../dpctl-capi/include/dpctl_data_types.h
EXCLUDE += ../dpctl-capi/include/dpctl_utils.h

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

MACRO_EXPANSION = NO
MACRO_EXPANSION = YES

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

EXPAND_ONLY_PREDEF = NO
EXPAND_ONLY_PREDEF = YES

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

EXPAND_AS_DEFINED =
EXPAND_AS_DEFINED = DPCTL_DECLARE_VECTOR

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

0 comments on commit f5cd7c7

Please sign in to comment.