IntelPython · diptorupd · Mar 27, 2021 · Mar 28, 2021 · Mar 28, 2021 · Mar 28, 2021
@@ -1,5 +1,8 @@
 docs
 generated_docs
+docfiles/dpctl-capi
 api
 build
 conf.py
+index.rst
+doxyrest-config.lua
@@ -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()
@@ -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
@@ -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
@@ -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.
@@ -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