From 294de13c9f5e68aa6d63925e790fffc1a09efe5b Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Sat, 27 Mar 2021 12:16:48 -0500 Subject: [PATCH 01/26] dpCtl -> dpctl in all rst filenames. --- docs/{dpCtl.dptensor_api.rst => dpctl.dptensor_api.rst} | 2 +- docs/{dpCtl.memory_api.rst => dpctl.memory_api.rst} | 4 ++-- docs/{dpCtl.program_api.rst => dpctl.program_api.rst} | 2 +- docs/{dpCtl_api.rst => dpctl_api.rst} | 2 +- docs/index.rst | 2 +- docs/toc_pyapi.rst | 8 ++++---- 6 files changed, 10 insertions(+), 10 deletions(-) rename docs/{dpCtl.dptensor_api.rst => dpctl.dptensor_api.rst} (85%) rename docs/{dpCtl.memory_api.rst => dpctl.memory_api.rst} (97%) rename docs/{dpCtl.program_api.rst => dpctl.program_api.rst} (95%) rename docs/{dpCtl_api.rst => dpctl_api.rst} (98%) diff --git a/docs/dpCtl.dptensor_api.rst b/docs/dpctl.dptensor_api.rst similarity index 85% rename from docs/dpCtl.dptensor_api.rst rename to docs/dpctl.dptensor_api.rst index da5486a3f7..7a3b571bd6 100644 --- a/docs/dpCtl.dptensor_api.rst +++ b/docs/dpctl.dptensor_api.rst @@ -1,4 +1,4 @@ -.. _dpCtl.dptensor_api: +.. _dpctl.dptensor_api: ######################### dpctl dptensor Python API diff --git a/docs/dpCtl.memory_api.rst b/docs/dpctl.memory_api.rst similarity index 97% rename from docs/dpCtl.memory_api.rst rename to docs/dpctl.memory_api.rst index fb2add31f5..1a0d4d6f72 100644 --- a/docs/dpCtl.memory_api.rst +++ b/docs/dpctl.memory_api.rst @@ -1,7 +1,7 @@ -.. _dpCtl.memory_api: +.. _dpctl.memory_api: ####################### -dpCtl Memory Python API +dpctl Memory Python API ####################### .. automodule:: dpctl.memory diff --git a/docs/dpCtl.program_api.rst b/docs/dpctl.program_api.rst similarity index 95% rename from docs/dpCtl.program_api.rst rename to docs/dpctl.program_api.rst index b6f68157c9..640fafe525 100644 --- a/docs/dpCtl.program_api.rst +++ b/docs/dpctl.program_api.rst @@ -1,4 +1,4 @@ -.. _dpCtl.program_api: +.. _dpctl.program_api: ######################## dpctl Program Python API diff --git a/docs/dpCtl_api.rst b/docs/dpctl_api.rst similarity index 98% rename from docs/dpCtl_api.rst rename to docs/dpctl_api.rst index 237ae9ce25..59133ee26a 100644 --- a/docs/dpCtl_api.rst +++ b/docs/dpctl_api.rst @@ -1,4 +1,4 @@ -.. _dpCtl_api: +.. _dpctl_api: ################ dpctl Python API diff --git a/docs/index.rst b/docs/index.rst index 07d8c01e39..8dca15f562 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -23,4 +23,4 @@ Indices and tables :caption: Contents: toc_pyapi - api/dpCtl-CAPI_root + api/dpctl-CAPI_root diff --git a/docs/toc_pyapi.rst b/docs/toc_pyapi.rst index c4119e0388..88c2587a07 100644 --- a/docs/toc_pyapi.rst +++ b/docs/toc_pyapi.rst @@ -4,7 +4,7 @@ Python API .. toctree:: :maxdepth: 1 - dpctl - SYCL runtime wrapper classes and queue manager - dpctl.dptensor - Data-parallel tensor containers - dpctl.memory - USM memory manager - dpctl.program - Program manager + dpctl - SYCL runtime wrapper classes and queue manager + dpctl.dptensor - Data-parallel tensor containers + dpctl.memory - USM memory manager + dpctl.program - Program manager From a0a8b8bd815556262b7f3960a2be9d8248f50eb0 Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Sun, 28 Mar 2021 15:46:04 -0500 Subject: [PATCH 02/26] Various fixes to C API doxygen comment strings. --- docs/Doxyfile.in | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index 16330d6c7d..a035eb78a9 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -920,6 +920,7 @@ RECURSIVE = YES EXCLUDE = ../dpctl-capi/build EXCLUDE += ../dpctl-capi/install EXCLUDE += ../dpctl-capi/tests +EXCLUDE += ../dpctl-capi/CMakeLists.txt # 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,7 +2162,7 @@ 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 @@ -2169,7 +2170,7 @@ MACRO_EXPANSION = NO # 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 +2211,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 From 3e1753f05fe01d31c8cfcd5a0378ad347afd110b Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Sun, 28 Mar 2021 16:24:43 -0500 Subject: [PATCH 03/26] Update the Python API rst. --- docs/dpctl_api.rst | 24 +++++++++++++++++------- dpctl/_sycl_device.pyx | 4 ++-- 2 files changed, 19 insertions(+), 9 deletions(-) diff --git a/docs/dpctl_api.rst b/docs/dpctl_api.rst index 59133ee26a..e585650b1a 100644 --- a/docs/dpctl_api.rst +++ b/docs/dpctl_api.rst @@ -22,6 +22,10 @@ Classes :members: :undoc-members: +.. autoclass:: dpctl.SyclPlatform + :members: + :undoc-members: + .. autoclass:: dpctl.SyclQueue :members: :undoc-members: @@ -41,21 +45,27 @@ Exceptions .. autoexception:: dpctl.SyclKernelInvalidRangeError .. autoexception:: dpctl.SyclKernelSubmitError .. autoexception:: dpctl.SyclQueueCreationError -.. autoexception:: dpctl.UnsupportedBackendError -.. autoexception:: dpctl.UnsupportedDeviceError Functions --------- +.. autofunction:: get_devices +.. autofunction:: select_accelerator_device +.. autofunction:: select_cpu_device +.. autofunction:: select_default_device +.. autofunction:: select_gpu_device +.. autofunction:: select_host_device +.. autofunction:: get_num_devices +.. autofunction:: has_cpu_devices +.. autofunction:: has_gpu_devices +.. autofunction:: has_accelerator_devices +.. autofunction:: has_host_device +.. autofunction:: get_platforms +.. autofunction:: lsplatform .. autofunction:: device_context -.. autofunction:: dump .. autofunction:: get_current_backend .. autofunction:: get_current_device_type .. autofunction:: get_current_queue -.. autofunction:: get_include .. autofunction:: get_num_activated_queues -.. autofunction:: get_num_platforms -.. autofunction:: get_num_devices -.. autofunction:: has_sycl_platforms .. autofunction:: is_in_device_context .. autofunction:: set_global_queue diff --git a/dpctl/_sycl_device.pyx b/dpctl/_sycl_device.pyx index a0f44569c0..6dda293f87 100644 --- a/dpctl/_sycl_device.pyx +++ b/dpctl/_sycl_device.pyx @@ -17,7 +17,8 @@ # distutils: language = c++ # cython: language_level=3 -""" Implements SyclDevice Cython extension type. +""" + Implements SyclDevice Cython extension type. """ from ._backend cimport ( @@ -184,7 +185,6 @@ cdef class SyclDevice(_SyclDevice): :func:`dpctl.select_gpu_device()`, :func:`dpctl.select_host_device()`. - :Example: .. code-block:: python From 72f55334d9a68e6105ca0c093ec052a6e9e0fc1d Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Sun, 28 Mar 2021 16:56:50 -0500 Subject: [PATCH 04/26] Reorganize Python docs. --- docs/dpctl_api.rst | 28 +++++++---------------- docs/dpctl_pyapi_classes/SyclContext.rst | 9 ++++++++ docs/dpctl_pyapi_classes/SyclDevice.rst | 10 ++++++++ docs/dpctl_pyapi_classes/SyclEvent.rst | 10 ++++++++ docs/dpctl_pyapi_classes/SyclPlatform.rst | 9 ++++++++ docs/dpctl_pyapi_classes/SyclQueue.rst | 9 ++++++++ docs/toc_pyapi.rst | 2 +- 7 files changed, 56 insertions(+), 21 deletions(-) create mode 100644 docs/dpctl_pyapi_classes/SyclContext.rst create mode 100644 docs/dpctl_pyapi_classes/SyclDevice.rst create mode 100644 docs/dpctl_pyapi_classes/SyclEvent.rst create mode 100644 docs/dpctl_pyapi_classes/SyclPlatform.rst create mode 100644 docs/dpctl_pyapi_classes/SyclQueue.rst diff --git a/docs/dpctl_api.rst b/docs/dpctl_api.rst index e585650b1a..998a4fd5df 100644 --- a/docs/dpctl_api.rst +++ b/docs/dpctl_api.rst @@ -9,26 +9,14 @@ dpctl Python API Classes ------- -.. autoclass:: dpctl.SyclContext - :members: - :undoc-members: - -.. autoclass:: dpctl.SyclDevice - :members: - :inherited-members: - :undoc-members: - -.. autoclass:: dpctl.SyclEvent - :members: - :undoc-members: - -.. autoclass:: dpctl.SyclPlatform - :members: - :undoc-members: - -.. autoclass:: dpctl.SyclQueue - :members: - :undoc-members: +.. toctree:: + :maxdepth: 1 + + dpctl_pyapi_classes/SyclContext + dpctl_pyapi_classes/SyclDevice + dpctl_pyapi_classes/SyclEvent + dpctl_pyapi_classes/SyclPlatform + dpctl_pyapi_classes/SyclQueue Enumerations ------------ diff --git a/docs/dpctl_pyapi_classes/SyclContext.rst b/docs/dpctl_pyapi_classes/SyclContext.rst new file mode 100644 index 0000000000..4620a73b9e --- /dev/null +++ b/docs/dpctl_pyapi_classes/SyclContext.rst @@ -0,0 +1,9 @@ +.. _SyclContext_api: + +################# +dpctl.SyclContext +################# + +.. autoclass:: dpctl.SyclContext + :members: + :undoc-members: diff --git a/docs/dpctl_pyapi_classes/SyclDevice.rst b/docs/dpctl_pyapi_classes/SyclDevice.rst new file mode 100644 index 0000000000..6ca34f70d8 --- /dev/null +++ b/docs/dpctl_pyapi_classes/SyclDevice.rst @@ -0,0 +1,10 @@ +.. _SyclDevice_api: + +################ +dpctl.SyclDevice +################ + +.. autoclass:: dpctl.SyclDevice + :members: + :inherited-members: + :undoc-members: diff --git a/docs/dpctl_pyapi_classes/SyclEvent.rst b/docs/dpctl_pyapi_classes/SyclEvent.rst new file mode 100644 index 0000000000..1ce4b19cef --- /dev/null +++ b/docs/dpctl_pyapi_classes/SyclEvent.rst @@ -0,0 +1,10 @@ +.. _SyclEvent_api: + +############### +dpctl.SyclEvent +############### + +.. autoclass:: dpctl.SyclEvent + :members: + :inherited-members: + :undoc-members: diff --git a/docs/dpctl_pyapi_classes/SyclPlatform.rst b/docs/dpctl_pyapi_classes/SyclPlatform.rst new file mode 100644 index 0000000000..ee6f0c95c2 --- /dev/null +++ b/docs/dpctl_pyapi_classes/SyclPlatform.rst @@ -0,0 +1,9 @@ +.. _SyclPlatform_api: + +################## +dpctl.SyclPlatform +################## + +.. autoclass:: dpctl.SyclPlatform + :members: + :undoc-members: diff --git a/docs/dpctl_pyapi_classes/SyclQueue.rst b/docs/dpctl_pyapi_classes/SyclQueue.rst new file mode 100644 index 0000000000..75990eb215 --- /dev/null +++ b/docs/dpctl_pyapi_classes/SyclQueue.rst @@ -0,0 +1,9 @@ +.. _SyclQueue_api: + +############### +dpctl.SyclQueue +############### + +.. autoclass:: dpctl.SyclQueue + :members: + :undoc-members: diff --git a/docs/toc_pyapi.rst b/docs/toc_pyapi.rst index 88c2587a07..72d42da695 100644 --- a/docs/toc_pyapi.rst +++ b/docs/toc_pyapi.rst @@ -1,5 +1,5 @@ Python API -================ +========== .. toctree:: :maxdepth: 1 From 954fc26a097cf70bd487401074049167f88a858a Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Sun, 28 Mar 2021 22:22:12 -0500 Subject: [PATCH 05/26] 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. --- docs/.gitignore | 3 + docs/CMakeLists.txt | 254 ++++++---- docs/Doxyfile.in | 7 +- docs/README.md | 93 +++- docs/cmake/FindDoxyrest.cmake | 35 ++ docs/cmake/FindSphinx.cmake | 1 - docs/conf.in | 42 +- docs/doxyrest-config.lua.in | 466 ++++++++++++++++++ docs/{dpctl_api.rst => dpctl_pyapi.rst} | 12 +- .../SyclContext.rst | 0 .../SyclDevice.rst | 0 .../SyclEvent.rst | 0 .../SyclPlatform.rst | 0 .../SyclQueue.rst | 0 docs/index_doxyrest.rst.in | 26 + docs/{index.rst => index_no_doxyrest.rst.in} | 1 - docs/toc_pyapi.rst | 2 +- 17 files changed, 798 insertions(+), 144 deletions(-) create mode 100644 docs/cmake/FindDoxyrest.cmake create mode 100644 docs/doxyrest-config.lua.in rename docs/{dpctl_api.rst => dpctl_pyapi.rst} (85%) rename docs/{dpctl_pyapi_classes => dpctl_pyapi}/SyclContext.rst (100%) rename docs/{dpctl_pyapi_classes => dpctl_pyapi}/SyclDevice.rst (100%) rename docs/{dpctl_pyapi_classes => dpctl_pyapi}/SyclEvent.rst (100%) rename docs/{dpctl_pyapi_classes => dpctl_pyapi}/SyclPlatform.rst (100%) rename docs/{dpctl_pyapi_classes => dpctl_pyapi}/SyclQueue.rst (100%) create mode 100644 docs/index_doxyrest.rst.in rename docs/{index.rst => index_no_doxyrest.rst.in} (95%) diff --git a/docs/.gitignore b/docs/.gitignore index 6e1b536b13..f34a564671 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,5 +1,8 @@ docs generated_docs +dpctl-capi-doxyrest api build conf.py +index.rst +doxyrest-config.lua \ No newline at end of file diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index abb6c6ce07..2fe505bd76 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -1,100 +1,188 @@ cmake_minimum_required(VERSION 3.18 FATAL_ERROR) project("Data-parallel Control (dpctl)") -# Add the cmake folder so the FindSphinx module is found -set(CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake" ${CMAKE_MODULE_PATH}) -find_package(Sphinx REQUIRED) -find_package(Doxygen REQUIRED) -find_package (Git) +# 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 +) -set(DOC_OUTPUT_DIR ${CMAKE_CURRENT_SOURCE_DIR}/generated_docs) -if( DPCTL_DOCGEN_PREFIX ) - message(STATUS "Generating dpctl documents in " ${DPCTL_DOCGEN_PREFIX}) - set(DOC_OUTPUT_DIR ${DPCTL_DOCGEN_PREFIX}) -endif() +# 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) -set(CURRENT_RELEASE "") + file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR}) -# 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 + # 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 ) - set(CURRENT_COMMIT "") - execute_process( - COMMAND ${GIT_EXECUTABLE} describe --tags - RESULT_VARIABLE result - OUTPUT_VARIABLE CURRENT_COMMIT - OUTPUT_STRIP_TRAILING_WHITESPACE + + # Target to generate only Doxygen documentation + add_custom_target( + Doxygen + ALL + DEPENDS ${DOXYGEN_INDEX_FILE} ) - if (NOT "${CURRENT_RELEASE}" STREQUAL "${CURRENT_COMMIT}") - set(CURRENT_RELEASE "master") - endif () -endif (GIT_FOUND) +endfunction() -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) +function(_setup_doxyrest) + set(DOXYREST_OUTPUT_DIR_NAME dpctl-capi-doxyrest) + 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() -# Replace variables inside @@ with the current values -configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY) +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) -file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR}) + # 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() -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 -) +function(_set_current_release) + 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) +endfunction() -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) +# 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) +if (DPCTL_ENABLE_DOXYREST) + find_package(Lua REQUIRED) + find_package(Doxyrest REQUIRED) +endif() -# 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" -) +# 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() -# 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() diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index a035eb78a9..cd278404ed 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -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,10 +917,7 @@ 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/CMakeLists.txt +EXCLUDE = # 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 diff --git a/docs/README.md b/docs/README.md index cb8f1da4b5..b1430df6a9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,30 +1,89 @@ What? ===== -Generator scripts for dpctl API documentation. To run these scripts, follow -the following steps: +This README provides the steps to generate the documentation for both the +C and Python API of dpctl. The documentation of dpctl can be generated either +as a set of consolidated HTML pages containing both Python and C API, or +separate set of pages for C API and Python API. It is suggested that the +consolidated documentation is generated using the provided build scripts. + +Prerequisite +============ + +The following tools are needed in order to build the documentation for dpctl + +- `Sphinx` +- `Doxygen` +- `Doxyrest` [optional] +- `Lua` [optional] + +`Doxyrest` and `Lua` are needed to generate `rst` files from the `Doxygen` +output and add them to a consolidate `Sphinx` generated site. It is preferred +that the latest `Doxyrest` binary is installed from +https://github.com/vovkos/doxyrest/tags. + +`Lua` is required if using `Doxyrest`. Please follow your OS specific +instructions to install `liblua`. *E.g.*, on Ubuntu 20.04: + +``` +sudo apt-get install liblua5.2-dev +``` + +Generating the docs +=================== + +The documentation should be generated using the provided `Cmake` build script. +There are a few configurable options that can be used to select the type of +documentation to generate. + +Build only Doxygen for C API +---------------------------- ```bash cd dpctl/docs mkdir build cd build -cmake -DDPCTL_DOCGEN_PREFIX= .. -make Sphinx +cmake .. +make Doxygen ``` +The above steps will generate the `Doxygen` files at +`dpctl/docs/generated_docs/doxygen/html`. The documentation can also be +generated at a custom location by providing the optional flag -The `DPCTL_DOCGEN_PREFIX` flag is optional and can be omitted to generate the -documents in the current source directory in a sub-directory called -`generated_docs`. +```bash +cd dpctl/docs +mkdir build +cd build +cmake .. -DDPCTL_DOCGEN_PREFIX= +make Doxygen +``` -The `make Sphinx` command will generate standalone Doxygen documentation and -a consolidated Sphinx documentation for both dpctl Python and C APIs. +Build only Sphinx for Python API +-------------------------------- +```bash +cd dpctl/docs +mkdir build +cd build +cmake .. -DDPCTL_DOCGEN_PREFIX= +make Sphinx +``` -Prerequisite -============ +The `make Sphinx` command will generate only the Python API docs for dpctl. -Before you generate the documentation make sure you have the following -packages installed: +Build consolidated docs +----------------------- +It is possible to generate a single site with both Python and C API docs. As +mentioned before, `Doxyrest` and `Lua` are required to generate the consolidated +site. -- sphinx -- doxygen -- breathe -- exhale +```bash +cd dpctl/docs +mkdir build +cd build +cmake .. \ + -DDPCTL_ENABLE_DOXYREST=ON \ + -DDoxyrest_DIR= \ + -DDPCTL_DOCGEN_PREFIX= +make Sphinx +``` +The `Doxyrest_DIR` flag is optional, but is needed when Doxyrest is installed in +a non-system location. diff --git a/docs/cmake/FindDoxyrest.cmake b/docs/cmake/FindDoxyrest.cmake new file mode 100644 index 0000000000..e37ca8bd02 --- /dev/null +++ b/docs/cmake/FindDoxyrest.cmake @@ -0,0 +1,35 @@ +include(FindPackageHandleStandardArgs) + +message(STATUS "Doxyrest_DIR ${Doxyrest_DIR}") + +find_file(DOXYREST_CONFIG_FILE + NAMES doxyrest_config.cmake + HINTS ${Doxyrest_DIR}/lib/cmake/doxyrest + $ENV{Doxyrest_DIR}/lib/cmake/doxyrest +) +find_file(DOXYREST_VERSION_FILE + NAMES doxyrest_version.cmake + HINTS ${Doxyrest_DIR}/lib/cmake/doxyrest + $ENV{Doxyrest_DIR}/lib/cmake/doxyrest +) + +if(DOXYREST_CONFIG_FILE) + include(${DOXYREST_CONFIG_FILE}) +endif() + +if(DOXYREST_VERSION_FILE) + include(${DOXYREST_VERSION_FILE}) +endif() + +# Handle standard arguments to find_package like REQUIRED and QUIET +find_package_handle_standard_args(Doxyrest DEFAULT_MSG + DOXYREST_EXE + DOXYREST_FRAME_DIR + DOXYREST_SPHINX_DIR + DOXYREST_EXE + DOXYREST_CMAKE_DIR + DOXYREST_VERSION_MAJOR + DOXYREST_VERSION_MINOR + DOXYREST_VERSION_REVISION + DOXYREST_VERSION_FULL +) diff --git a/docs/cmake/FindSphinx.cmake b/docs/cmake/FindSphinx.cmake index 708d928c1c..990f979cb0 100644 --- a/docs/cmake/FindSphinx.cmake +++ b/docs/cmake/FindSphinx.cmake @@ -9,4 +9,3 @@ include(FindPackageHandleStandardArgs) find_package_handle_standard_args(Sphinx "Failed to find sphinx-build executable" SPHINX_EXECUTABLE) - diff --git a/docs/conf.in b/docs/conf.in index cda6b93b73..1f6d9425a7 100644 --- a/docs/conf.in +++ b/docs/conf.in @@ -27,8 +27,6 @@ release = "@CURRENT_RELEASE@" # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - "breathe", - "exhale", "sphinx.ext.todo", "sphinx.ext.coverage", "sphinx.ext.viewcode", @@ -37,8 +35,17 @@ extensions = [ "sphinx.ext.napoleon", ] -# Breathe Configuration -breathe_default_project = "dpctl-CAPI" +use_doxyrest = "@DPCTL_ENABLE_DOXYREST@" + +if len(use_doxyrest): + # Specify the path to Doxyrest extensions for Sphinx: + import sys, os + + sys.path.insert( + 1, + os.path.abspath("@DOXYREST_SPHINX_DIR@"), + ) + extensions += ["doxyrest", "cpplexer"] # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] @@ -54,32 +61,7 @@ source_suffix = ".rst" # This pattern also affects html_static_path and html_extra_path. exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] -# Setup the exhale extension -exhale_args = { - # These arguments are required - "containmentFolder": "./api", - "rootFileName": "dpctl-CAPI_root.rst", - "rootFileTitle": "dpctl C API", - "doxygenStripFromPath": "..", - "createTreeView": True, - "exhaleExecutesDoxygen": True, - # "exhaleUseDoxyfile": True, - "exhaleDoxygenStdin": textwrap.dedent( - """ - INPUT = ../dpctl-capi/include - REPEAT_BRIEF=YES - OPTIMIZE_OUTPUT_FOR_C=YES - OPTIMIZE_OUTPUT_JAVA= NO - EXTRACT_ALL=YES - EXCLUDE= ../dpctl-capi/build - EXCLUDE+= ../dpctl-capi/install - EXCLUDE+= ../dpctl-capi/tests - EXCLUDE_PATTERNS = CMakeLists.txt - """ - ), -} - -highlight_language = "c" +highlight_language = "C" # The name of the Pygments (syntax highlighting) style to use. pygments_style = "sphinx" diff --git a/docs/doxyrest-config.lua.in b/docs/doxyrest-config.lua.in new file mode 100644 index 0000000000..980260e611 --- /dev/null +++ b/docs/doxyrest-config.lua.in @@ -0,0 +1,466 @@ +-------------------------------------------------------------------------------- +-- +-- This file is part of the Doxyrest toolkit. +-- +-- Doxyrest is distributed under the MIT license. +-- For details see accompanying license.txt file, +-- the public copy of which is also available at: +-- http://tibbo.com/downloads/archive/doxyrest/license.txt +-- +-------------------------------------------------------------------------------- + +--! +--! \defgroup frame-config +--! \grouporder 2 +--! \title Frame Settings +--! +--! This section describes frame settings controlling input and output paths, +--! titles, force-includes, declaration coding style, etc. +--! +--! A default ``doxyrest-config.lua`` file for standard frames can be found at +--! ``$DOXYREST_FRAME_DIR/doxyrest-config.lua``. Copy it to your project +--! directory and then adjust all the necessary parameters. +--! +--! @{ +--! + +--! +--! Table containing a list of frame directories. All frame files will be +--! searched in directories -- and in the sequence -- specified here. +--! + +FRAME_DIR_LIST = { + "@DOXYREST_FRAME_DIR@/cfamily", + "@DOXYREST_FRAME_DIR@/common" +} + +--! +--! The output master (index) reStructuredText file. Usually, the index frame +--! also generates auxillary files -- they will be placed next to the master +--! file. The command line option ``-f`` *overrides* this value. +--! If neither ``FRAME_FILE`` nor ``-f`` is specified, ``index.rst.in`` will be +--! used as the default frame file. +--! + +FRAME_FILE = "index.rst.in" + +--! +--! The input master (index) XML file. Specifying it here allows calling +--! ``doxyrest`` without parameters; otherwise, the master XML *must* be passed +--! via the command line. If both ``INPUT_FILE`` and command line parameter are +--! specified, the command line takes precedence. +--! + +INPUT_FILE = "@DOXYGEN_OUTPUT_DIR@/xml/index.xml" + +--! +--! The output master (index) reStructuredText file. Usually, the index frame +--! also generates auxillary files -- they will be placed next to the master +--! file. The command line option ``-o`` *overrides* this value. If neither +--! ``OUTPUT_FILE`` nor ``-o`` is specified, ``index.rst`` will be used as +--! the default output master file. +--! + +OUTPUT_FILE = "@DOXYREST_OUTPUT_DIR@/index.rst" + +--! +--! File with project-specific reStructuredText definitions. When non``nil``, +--! this file will be included at the top of every generated ``.rst`` file. +--! + +FORCE_INCLUDE_FILE = nil + +--! +--! If you want to add extra reStructuredText documentation pages, do so +--! by adding them to this list. +--! + +EXTRA_PAGE_LIST = {} + +--! +--! The title of the main (index) page. This only is used when ``INTRO_FILE`` +--! is not set (otherwise, the title of intro file will be used). +--! + +INDEX_TITLE = "dpctl C API" + +--! +--! File with project introduction (reStructuredText). When non-nil, this file +--! will be included into ``index.rst`` file and NOT added to the list of other +--! documentation pages. +--! + +INTRO_FILE = nil + +--! +--! Specify whether to sort groups lexicographically (by ``title``) or +--! logically (by ``id``). To maintain the original order (in which a group has +--! been seen in the XML database), use ``originalIdx``. +--! +--! Omitting ``SORT_GROUPS_BY`` (or setting it to ``nil``) results in groups +--! being sorted by ``title``. +--! + +SORT_GROUPS_BY = "title" + +--[[! + By default, the page for the global namespace page will be called + "Global Namespace" and will contain no description except that for the + global compounds and members. + + It's possible to override this behaviour by defining an auxillary compound + (page or group) with a special ``id``; this page/group may contain a + user-defined title, a brief description and a detailed description. Use + ``GLOBAL_AUX_COMPOUND_ID`` to define this special id. + + .. note:: + + To make sure you use the correct **Doxygen** XML ID of the group/page, + find the definition of the group in one of ``.xml`` files and copy + the value of ``id`` attribute. + + For example, if the group was declared as ``\defgroup global`` then + the its ``id`` will probably be either ``group_`` or + ``group__``. +]] + +GLOBAL_AUX_COMPOUND_ID = "group_global" + +--[[! + Doxyrest offers a workaround for the lack of footnotes in Doxygen by + getting documentation blocks for specially named pseudo-members and + converting those into footnotes. + + ``FOOTNOTE_MEMBER_PREFIX`` specifies the name prefix for such + pseudo-members. If it is set to ``nil`` or an empty string, Doxyrest + will not attempt to convert any members to footnotes. + + \sa :ref:`footnotes` +]] + +FOOTNOTE_MEMBER_PREFIX = nil + +--! +--! Specify the main language of your project; this string will be used for +--! the reStructuredText ``.. code-block::`` sections and for conditional +--! formatting of module item declarations. +--! + +LANGUAGE = C + +--! +--! Convert ``\verbatim`` sections in doxy-comments to ``.. code-block::`` +--! sections in the output reStructuredText. The string value of +--! ``VERBATIM_TO_CODE_BLOCK`` will be used as the language of +--! ``.. code-block::`` section. By default, it's ``"none"`` which results in +--! no syntax highlighting. To disable conversion at all, use ``nil``. +--! + +VERBATIM_TO_CODE_BLOCK = "CPP" + +--! +--! If the original doxy comments contain asterisks, they have to be escaped in +--! reStructuredText (asterisks are used to mark **bold** or *italic* blocks). +--! + +ESCAPE_ASTERISKS = true + +--! +--! If the original doxy comments contain pipe characters ``|``, they have to be +--! escaped in reStructuredText (pipes are used for substitution references). +--! + +ESCAPE_PIPES = true + +--! +--! If the original doxy comments contain trailingasterisks, they have to be +--! escaped in reStructuredText (trailing underscores are used for internal +--! links). +--! + +ESCAPE_TRAILING_UNDERSCORES = true + +--! +--! Exclude items declared in specific locations. Use a regular expression to +--! define a mask of directories/source files to completely exclude from the +--! final documentation. For example, ``.*/impl/.*lua$`` will exclude all +--! ``.lua`` files located in ``impl/`` directory. +--! + +EXCLUDE_LOCATION_PATTERN = nil + +--! +--! Exclude variables and functions without any documentation (no doxy-comments). +--! + +EXCLUDE_UNDOCUMENTED_ITEMS = true + +--! +--! \subgroup +--! +--! By default, Doxyrest tries to translate Doxygen ``\section``, +--! ``\subsection``, and ``\subsubsection`` commands (as well as the +--! ```` blocks generated by Doxygen from Markdown titles +--! inside comments) into reStructuredText titles. +--! +--! This sometimes leads to problems because Doxygen headings may appear outside +--! of the global scope (e.g. inside lists) while reStructuredText titles are +--! only allowed at the global scope. Another issue is Doxygen headings may +--! yield inconsistent title structure (e.g. a title level 1 followed by level +--! 3). +--! +--! If you run into these issues, use ``SECTION_TO_RUBRIC`` or +--! ``HEADING_TO_RUBRIC`` to always convert Doxygen sections or ```` +--! blocks or into reStructuredText ``.. rubric::`` directives. This yields +--! uni-level headings, but solves both aforementioned problems. +--! + +SECTION_TO_RUBRIC = false +HEADING_TO_RUBRIC = false + +--[[! + By default, Doxyrest frames build a Python dictionary to be used later on by + the ``:cref:`` (code-reference) role. This database maps language-specific + qualified names of items to their IDs. + + This, together with setting the Sphinx ``default_role`` to ``cref``, allows + to conveniently reference items from Doxy-comments or regular ``.rst`` files + as such: + + .. code-block:: none + + The `ui::Dialog` class is a base to the `ui::FileDialog` class. + + However, if this facility is not used, building (and loading) of the + cref-database can be omitted to save both space and time. +]] + +CREF_DB = false + +--[[! + Exclude items with higher protection level than ``PROTECTION_FILTER``: + + 1. ``public`` + 2. ``protected`` + 3. ``private`` + 4. ``package`` + + By default, only public items are included into documentation. +]] + +PROTECTION_FILTER = "public" + +--! +--! In many projects empty defines are *only* used as include-guards (and as +--! such, should be excluded from the documentation). If this is not the case +--! and empty defines should be kept in the final documentation, change this +--! setting to ``false``. +--! + +EXCLUDE_EMPTY_DEFINES = false + +--! +--! If non-``nil``, each define will be checked using this regular expression +--! and if its name matches, this define will be excluded from the documentation. +--! + +EXCLUDE_DEFINE_PATTERN = nil + +--! +--! Usually providing documentation blocks for default constructors is +--! not necessary (as to avoid redundant meaningless "Constructs a new object" +--! paragraphs). Change this to ``false`` if default constructors *should* be +--! included. +--! + +EXCLUDE_DEFAULT_CONSTRUCTORS = true + +--! +--! Usually providing documentation blocks for a destructors is +--! not necessary (as to avoid redundant meaningless "Destructs an object" +--! paragraphs). Change this to ``false`` if destructors *should* be +--! included. +--! + +EXCLUDE_DESTRUCTORS = true + +--[[! + Usually providing documentation blocks for primitive C typedefs such as: + + .. code-block:: C + + typedef struct S S; + + is not necessary. Change this to ``false`` if such typedefs *should* be + included. +]] + +EXCLUDE_PRIMITIVE_TYPEDEFS = true + +--! +--! For a base class/struct, show all the types directly derived from it. +--! + +SHOW_DIRECT_DESCENDANTS = true + +--[[! + \subgroup + + Insert space between function name and parameter list like this: + + .. code-block:: C + + void foo (); + + By default, ``PRE_PARAM_LIST_SPACE`` is ``false`` which yields: + + .. code-block:: C + + void foo(); +]] + +PRE_PARAM_LIST_SPACE = false +PRE_OPERATOR_NAME_SPACE = true +PRE_OPERATOR_PARAM_LIST_SPACE = true + +--[[! + Insert a new line before the body of a enum, struct, class, etc. + + When ``PRE_BODY_NL`` is ``false``: + + .. code-block:: cpp + + class MyClass { + ... + } + + When ``PRE_BODY_NL`` is ``true``: + + .. code-block:: cpp + + class MyClass + { + ... + } +]] + +PRE_BODY_NL = true + +--[[! + Use multi-line parameter lists in function declarations if parameter count is + greater than this threshold. ``nil`` means don't use parameter count + threshold. + + For example, when ``ML_PARAM_LIST_COUNT_THRESHOLD`` is ``2``, the function + declarations will look as such: + + .. code-block:: C + + void fn0(); + void fn1(int a); + void fn2(int a, int b); + + void fn3( + int a, + int b + int c + ); +]] + +ML_PARAM_LIST_COUNT_THRESHOLD = nill + +--[[! + Use multi-line parameter lists in function declarations if single-line + declaration length parameter count is greater than this threshold. + ``nil`` means don't use length threshold. + + Similar to ``ML_PARAM_LIST_COUNT_THRESHOLD``, but the threshold parameter + here is *declaration length* and not *declaration parameter count*. + + Example: + + .. code-block:: C + + void foo(int a, int b, int c); + + void bar( + int veryLongParameterName, + int anotherVeryLongParameterName + ); + +]] + +ML_PARAM_LIST_LENGTH_THRESHOLD = 80 + +--[[! + Use multi-line specifier-modifier lists in function declarations, i.e + allocate a dedicated line for each type specifier/morifier. + + For example, when ``ML_SPECIFIER_MODIFIER_LIST`` is ``true``, the function + declarations will look as such: + + .. code-block:: C + + void + foo(); + + static + bool + __cdecl + bar(int a); +]] + +ML_SPECIFIER_MODIFIER_LIST = true + +--[[! + Use the new C++11 syntax for ``typedef``-s: + + When ``TYPEDEF_TO_USING`` is ``false``: + + .. code-block:: cpp + + typedef unsigned int uint_t; + typedef void Foo(int); + typedef void (*FooPtr)(int); + + When ``TYPEDEF_TO_USING`` is ``true``: + + .. code-block:: cpp + + using uint_t = unsigned int; + using Foo typedef void (int); + using FooPtr typedef void (*)(int); +]] + +TYPEDEF_TO_USING = false + +--[[! + Sometimes, it's required to redirect a Doxygen link to some external location. + In this case, add an entry to ``EXTERNAL_CREF_DB`` with the target URL, e.g.: + + .. code-block:: lua + + EXTERNAL_CREF_DB = + { + [ "jnc.Scheduler" ] = "https://vovkos.github.io/jancy/stdlib/class_jnc_Scheduler.html", + [ "strlen"] = "https://vovkos.github.io/jancy/stdlib/group_crt.html#doxid-function-strlen" + + -- ... + } + + The key of the map is an ``importid`` attribute. This is a non-standard Doxygen + attribute; Jancy compiler generates is when a referenced item is contained in an + imported extensions library (``.jncx``) +]] + +EXTERNAL_CREF_DB = {} + +--[[! + Usually providing documentation blocks for Lua ``local`` variables or + functions is not desired. Change this to ``false`` if local items + *should* be included in the final documentation. +]] + +EXCLUDE_LUA_LOCALS = true + +--! @} diff --git a/docs/dpctl_api.rst b/docs/dpctl_pyapi.rst similarity index 85% rename from docs/dpctl_api.rst rename to docs/dpctl_pyapi.rst index 998a4fd5df..dba5c7d6ff 100644 --- a/docs/dpctl_api.rst +++ b/docs/dpctl_pyapi.rst @@ -1,4 +1,4 @@ -.. _dpctl_api: +.. _dpctl_pyapi: ################ dpctl Python API @@ -12,11 +12,11 @@ Classes .. toctree:: :maxdepth: 1 - dpctl_pyapi_classes/SyclContext - dpctl_pyapi_classes/SyclDevice - dpctl_pyapi_classes/SyclEvent - dpctl_pyapi_classes/SyclPlatform - dpctl_pyapi_classes/SyclQueue + dpctl_pyapi/SyclContext + dpctl_pyapi/SyclDevice + dpctl_pyapi/SyclEvent + dpctl_pyapi/SyclPlatform + dpctl_pyapi/SyclQueue Enumerations ------------ diff --git a/docs/dpctl_pyapi_classes/SyclContext.rst b/docs/dpctl_pyapi/SyclContext.rst similarity index 100% rename from docs/dpctl_pyapi_classes/SyclContext.rst rename to docs/dpctl_pyapi/SyclContext.rst diff --git a/docs/dpctl_pyapi_classes/SyclDevice.rst b/docs/dpctl_pyapi/SyclDevice.rst similarity index 100% rename from docs/dpctl_pyapi_classes/SyclDevice.rst rename to docs/dpctl_pyapi/SyclDevice.rst diff --git a/docs/dpctl_pyapi_classes/SyclEvent.rst b/docs/dpctl_pyapi/SyclEvent.rst similarity index 100% rename from docs/dpctl_pyapi_classes/SyclEvent.rst rename to docs/dpctl_pyapi/SyclEvent.rst diff --git a/docs/dpctl_pyapi_classes/SyclPlatform.rst b/docs/dpctl_pyapi/SyclPlatform.rst similarity index 100% rename from docs/dpctl_pyapi_classes/SyclPlatform.rst rename to docs/dpctl_pyapi/SyclPlatform.rst diff --git a/docs/dpctl_pyapi_classes/SyclQueue.rst b/docs/dpctl_pyapi/SyclQueue.rst similarity index 100% rename from docs/dpctl_pyapi_classes/SyclQueue.rst rename to docs/dpctl_pyapi/SyclQueue.rst diff --git a/docs/index_doxyrest.rst.in b/docs/index_doxyrest.rst.in new file mode 100644 index 0000000000..3191018211 --- /dev/null +++ b/docs/index_doxyrest.rst.in @@ -0,0 +1,26 @@ +.. Data-parallel Control (dpctl) documentation master file, created by + sphinx-quickstart on Sat Oct 17 19:02:45 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Data-parallel Control (dpctl)'s documentation! +========================================================= + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + +.. toctree:: + :maxdepth: 3 + :caption: Contents: + + toc_pyapi + @DOXYREST_OUTPUT_DIR_NAME@/index diff --git a/docs/index.rst b/docs/index_no_doxyrest.rst.in similarity index 95% rename from docs/index.rst rename to docs/index_no_doxyrest.rst.in index 8dca15f562..87192ef66d 100644 --- a/docs/index.rst +++ b/docs/index_no_doxyrest.rst.in @@ -23,4 +23,3 @@ Indices and tables :caption: Contents: toc_pyapi - api/dpctl-CAPI_root diff --git a/docs/toc_pyapi.rst b/docs/toc_pyapi.rst index 72d42da695..a0c8609530 100644 --- a/docs/toc_pyapi.rst +++ b/docs/toc_pyapi.rst @@ -4,7 +4,7 @@ Python API .. toctree:: :maxdepth: 1 - dpctl - SYCL runtime wrapper classes and queue manager + dpctl - SYCL runtime wrapper classes and queue manager dpctl.dptensor - Data-parallel tensor containers dpctl.memory - USM memory manager dpctl.program - Program manager From 738df28bf20fd512bbd8bf137dbe946260e9a6f0 Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Tue, 30 Mar 2021 13:01:37 -0500 Subject: [PATCH 06/26] Reorganize rst files into a sub-folder. --- docs/conf.in | 3 ++- docs/{ => docfiles}/dpctl.dptensor_api.rst | 0 docs/{ => docfiles}/dpctl.memory_api.rst | 0 docs/{ => docfiles}/dpctl.program_api.rst | 0 docs/{ => docfiles}/dpctl_pyapi.rst | 0 .../dpctl_pyapi/SyclContext.rst | 0 .../{ => docfiles}/dpctl_pyapi/SyclDevice.rst | 0 docs/{ => docfiles}/dpctl_pyapi/SyclEvent.rst | 0 .../dpctl_pyapi/SyclPlatform.rst | 0 docs/{ => docfiles}/dpctl_pyapi/SyclQueue.rst | 0 docs/docfiles/intro.rst | 20 +++++++++++++++++++ docs/{ => docfiles}/toc_pyapi.rst | 0 docs/index_doxyrest.rst.in | 17 ++-------------- docs/index_no_doxyrest.rst.in | 17 ++-------------- 14 files changed, 26 insertions(+), 31 deletions(-) rename docs/{ => docfiles}/dpctl.dptensor_api.rst (100%) rename docs/{ => docfiles}/dpctl.memory_api.rst (100%) rename docs/{ => docfiles}/dpctl.program_api.rst (100%) rename docs/{ => docfiles}/dpctl_pyapi.rst (100%) rename docs/{ => docfiles}/dpctl_pyapi/SyclContext.rst (100%) rename docs/{ => docfiles}/dpctl_pyapi/SyclDevice.rst (100%) rename docs/{ => docfiles}/dpctl_pyapi/SyclEvent.rst (100%) rename docs/{ => docfiles}/dpctl_pyapi/SyclPlatform.rst (100%) rename docs/{ => docfiles}/dpctl_pyapi/SyclQueue.rst (100%) create mode 100644 docs/docfiles/intro.rst rename docs/{ => docfiles}/toc_pyapi.rst (100%) diff --git a/docs/conf.in b/docs/conf.in index 1f6d9425a7..f0ed9db81e 100644 --- a/docs/conf.in +++ b/docs/conf.in @@ -33,6 +33,7 @@ extensions = [ "sphinx.ext.githubpages", "sphinx.ext.autodoc", "sphinx.ext.napoleon", + "sphinx.ext.todo", ] use_doxyrest = "@DPCTL_ENABLE_DOXYREST@" @@ -61,7 +62,7 @@ source_suffix = ".rst" # This pattern also affects html_static_path and html_extra_path. exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] -highlight_language = "C" +highlight_language = "Python" # The name of the Pygments (syntax highlighting) style to use. pygments_style = "sphinx" diff --git a/docs/dpctl.dptensor_api.rst b/docs/docfiles/dpctl.dptensor_api.rst similarity index 100% rename from docs/dpctl.dptensor_api.rst rename to docs/docfiles/dpctl.dptensor_api.rst diff --git a/docs/dpctl.memory_api.rst b/docs/docfiles/dpctl.memory_api.rst similarity index 100% rename from docs/dpctl.memory_api.rst rename to docs/docfiles/dpctl.memory_api.rst diff --git a/docs/dpctl.program_api.rst b/docs/docfiles/dpctl.program_api.rst similarity index 100% rename from docs/dpctl.program_api.rst rename to docs/docfiles/dpctl.program_api.rst diff --git a/docs/dpctl_pyapi.rst b/docs/docfiles/dpctl_pyapi.rst similarity index 100% rename from docs/dpctl_pyapi.rst rename to docs/docfiles/dpctl_pyapi.rst diff --git a/docs/dpctl_pyapi/SyclContext.rst b/docs/docfiles/dpctl_pyapi/SyclContext.rst similarity index 100% rename from docs/dpctl_pyapi/SyclContext.rst rename to docs/docfiles/dpctl_pyapi/SyclContext.rst diff --git a/docs/dpctl_pyapi/SyclDevice.rst b/docs/docfiles/dpctl_pyapi/SyclDevice.rst similarity index 100% rename from docs/dpctl_pyapi/SyclDevice.rst rename to docs/docfiles/dpctl_pyapi/SyclDevice.rst diff --git a/docs/dpctl_pyapi/SyclEvent.rst b/docs/docfiles/dpctl_pyapi/SyclEvent.rst similarity index 100% rename from docs/dpctl_pyapi/SyclEvent.rst rename to docs/docfiles/dpctl_pyapi/SyclEvent.rst diff --git a/docs/dpctl_pyapi/SyclPlatform.rst b/docs/docfiles/dpctl_pyapi/SyclPlatform.rst similarity index 100% rename from docs/dpctl_pyapi/SyclPlatform.rst rename to docs/docfiles/dpctl_pyapi/SyclPlatform.rst diff --git a/docs/dpctl_pyapi/SyclQueue.rst b/docs/docfiles/dpctl_pyapi/SyclQueue.rst similarity index 100% rename from docs/dpctl_pyapi/SyclQueue.rst rename to docs/docfiles/dpctl_pyapi/SyclQueue.rst diff --git a/docs/docfiles/intro.rst b/docs/docfiles/intro.rst new file mode 100644 index 0000000000..b08a7f8bb4 --- /dev/null +++ b/docs/docfiles/intro.rst @@ -0,0 +1,20 @@ +Welcome to Data-parallel Control (dpctl)'s documentation! +========================================================= + +Data-parallel control (``dpctl``) is a library that exposes SYCL and DPCPP to +languages other than C++. Currently, ``dpctl`` provides SYCL bindings for C and +Python making it possible to access SYCL runtime objects and methods from these +languages. The SYCL functionality covered by ``dpctl`` includes the core SYCL runtime classes described in Section 4.6 of the `SYCL 2020 spec `_ and USM memory management. ``Dpctl`` also has experimental support for DPCPP ``kernel`` and ``program`` classes. + + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/toc_pyapi.rst b/docs/docfiles/toc_pyapi.rst similarity index 100% rename from docs/toc_pyapi.rst rename to docs/docfiles/toc_pyapi.rst diff --git a/docs/index_doxyrest.rst.in b/docs/index_doxyrest.rst.in index 3191018211..c37694f367 100644 --- a/docs/index_doxyrest.rst.in +++ b/docs/index_doxyrest.rst.in @@ -3,24 +3,11 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to Data-parallel Control (dpctl)'s documentation! -========================================================= - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +.. include:: ./docfiles/intro.rst .. toctree:: :maxdepth: 3 :caption: Contents: - toc_pyapi + docfiles/toc_pyapi @DOXYREST_OUTPUT_DIR_NAME@/index diff --git a/docs/index_no_doxyrest.rst.in b/docs/index_no_doxyrest.rst.in index 87192ef66d..f04e134648 100644 --- a/docs/index_no_doxyrest.rst.in +++ b/docs/index_no_doxyrest.rst.in @@ -3,23 +3,10 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to Data-parallel Control (dpctl)'s documentation! -========================================================= - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +.. include:: ./docfiles/intro.rst .. toctree:: :maxdepth: 3 :caption: Contents: - toc_pyapi + docfiles/toc_pyapi From 6aef253734eaedfffebc5c15a105b3047ca7b57f Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Tue, 30 Mar 2021 17:43:09 -0500 Subject: [PATCH 07/26] Few more tweaks. --- docs/Doxyfile.in | 8 ++++++-- docs/doxyrest-config.lua.in | 4 ++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index cd278404ed..bc6fdc3b22 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -917,7 +917,11 @@ RECURSIVE = YES # Note that relative paths are relative to the directory from which doxygen is # run. -EXCLUDE = +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 @@ -933,7 +937,7 @@ EXCLUDE_SYMLINKS = NO # Note that the wildcards are matched against the file with absolute path, so to # exclude all test directories for example use the pattern */test/* -EXCLUDE_PATTERNS = +EXCLUDE_PATTERNS = # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names # (namespaces, classes, functions, etc.) that should be excluded from the diff --git a/docs/doxyrest-config.lua.in b/docs/doxyrest-config.lua.in index 980260e611..e837c73e6a 100644 --- a/docs/doxyrest-config.lua.in +++ b/docs/doxyrest-config.lua.in @@ -257,14 +257,14 @@ PROTECTION_FILTER = "public" --! setting to ``false``. --! -EXCLUDE_EMPTY_DEFINES = false +EXCLUDE_EMPTY_DEFINES = true --! --! If non-``nil``, each define will be checked using this regular expression --! and if its name matches, this define will be excluded from the documentation. --! -EXCLUDE_DEFINE_PATTERN = nil +EXCLUDE_DEFINE_PATTERN = "DPCTL_API" --! --! Usually providing documentation blocks for default constructors is From 4dcb57b45b3ba329a9834e1081783192d5346ed1 Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Tue, 30 Mar 2021 21:16:39 -0500 Subject: [PATCH 08/26] Add stubs... --- docs/docfiles/intro.rst | 32 +++++++++++++++++++++----------- docs/docfiles/toc_pyapi.rst | 7 ++++--- docs/doxyrest-config.lua.in | 2 +- docs/index_doxyrest.rst.in | 6 ++++-- docs/index_no_doxyrest.rst.in | 6 ++++-- 5 files changed, 34 insertions(+), 19 deletions(-) diff --git a/docs/docfiles/intro.rst b/docs/docfiles/intro.rst index b08a7f8bb4..8da8cddd8d 100644 --- a/docs/docfiles/intro.rst +++ b/docs/docfiles/intro.rst @@ -1,20 +1,30 @@ Welcome to Data-parallel Control (dpctl)'s documentation! ========================================================= -Data-parallel control (``dpctl``) is a library that exposes SYCL and DPCPP to -languages other than C++. Currently, ``dpctl`` provides SYCL bindings for C and +Data-parallel control (dpctl) is a library that exposes SYCL and DPCPP to +languages other than C++. Currently, dpctl provides SYCL bindings for C and Python making it possible to access SYCL runtime objects and methods from these -languages. The SYCL functionality covered by ``dpctl`` includes the core SYCL runtime classes described in Section 4.6 of the `SYCL 2020 spec `_ and USM memory management. ``Dpctl`` also has experimental support for DPCPP ``kernel`` and ``program`` classes. +languages. The SYCL functionality covered by dpctl includes the core SYCL +runtime classes described in Section 4.6 of the +`SYCL 2020 spec `_ +and USM memory management. dpctl also has experimental support for SYCL's +``kernel`` and ``program`` classes. +Core Features +------------- -.. toctree:: - :maxdepth: 2 - :caption: Contents: +.. todo:: + Coming soon. -Indices and tables -================== +User Guidies +------------ + +.. todo:: + + Device Management. + +.. todo:: + + USM Memory Management -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/docfiles/toc_pyapi.rst b/docs/docfiles/toc_pyapi.rst index a0c8609530..50ccd6cfcc 100644 --- a/docs/docfiles/toc_pyapi.rst +++ b/docs/docfiles/toc_pyapi.rst @@ -1,10 +1,11 @@ -Python API -========== +dpctl Python API +================ .. toctree:: - :maxdepth: 1 + :hidden: dpctl - SYCL runtime wrapper classes and queue manager dpctl.dptensor - Data-parallel tensor containers dpctl.memory - USM memory manager dpctl.program - Program manager + diff --git a/docs/doxyrest-config.lua.in b/docs/doxyrest-config.lua.in index e837c73e6a..857260ddeb 100644 --- a/docs/doxyrest-config.lua.in +++ b/docs/doxyrest-config.lua.in @@ -146,7 +146,7 @@ FOOTNOTE_MEMBER_PREFIX = nil --! formatting of module item declarations. --! -LANGUAGE = C +LANGUAGE = CPP --! --! Convert ``\verbatim`` sections in doxy-comments to ``.. code-block::`` diff --git a/docs/index_doxyrest.rst.in b/docs/index_doxyrest.rst.in index c37694f367..c08594df1b 100644 --- a/docs/index_doxyrest.rst.in +++ b/docs/index_doxyrest.rst.in @@ -6,8 +6,10 @@ .. include:: ./docfiles/intro.rst .. toctree:: - :maxdepth: 3 - :caption: Contents: + :maxdepth: 1 + :caption: API Documentation docfiles/toc_pyapi @DOXYREST_OUTPUT_DIR_NAME@/index + +.. include:: ./docfiles/boilerplate.rst diff --git a/docs/index_no_doxyrest.rst.in b/docs/index_no_doxyrest.rst.in index f04e134648..3a624d2632 100644 --- a/docs/index_no_doxyrest.rst.in +++ b/docs/index_no_doxyrest.rst.in @@ -6,7 +6,9 @@ .. include:: ./docfiles/intro.rst .. toctree:: - :maxdepth: 3 - :caption: Contents: + :maxdepth: 1 + :caption: API Documentation docfiles/toc_pyapi + +.. include:: ./docfiles/boilerplate.rst From cdd68d32e6e4b349ed77b8215a625b20299bb424 Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Wed, 31 Mar 2021 08:51:01 -0500 Subject: [PATCH 09/26] add new line. --- docs/.gitignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/.gitignore b/docs/.gitignore index f34a564671..eab5cd6f4e 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -5,4 +5,4 @@ api build conf.py index.rst -doxyrest-config.lua \ No newline at end of file +doxyrest-config.lua From f9bea92774bb7ad8c48ecb267beb2af52c200342 Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Sun, 4 Apr 2021 21:14:04 -0500 Subject: [PATCH 10/26] Add boilerplate stuff. --- docs/conf.in | 2 +- docs/docfiles/boilerplate.rst | 19 +++++++++++++++++++ 2 files changed, 20 insertions(+), 1 deletion(-) create mode 100644 docs/docfiles/boilerplate.rst diff --git a/docs/conf.in b/docs/conf.in index f0ed9db81e..dcb3a2915e 100644 --- a/docs/conf.in +++ b/docs/conf.in @@ -38,7 +38,7 @@ extensions = [ use_doxyrest = "@DPCTL_ENABLE_DOXYREST@" -if len(use_doxyrest): +if use_doxyrest == "ON": # Specify the path to Doxyrest extensions for Sphinx: import sys, os diff --git a/docs/docfiles/boilerplate.rst b/docs/docfiles/boilerplate.rst new file mode 100644 index 0000000000..a10ea9bdb2 --- /dev/null +++ b/docs/docfiles/boilerplate.rst @@ -0,0 +1,19 @@ +About +===== + +dpctl is developed by Intel and is part of the `Intel Distribution for +Python `_. + +Contributing +============ + +Refer the `contributing guide `_ +for information on coding style and standards used in dpctl. + +License +======= + +dpctl is Licensed under Apache License 2.0 that can be found in +`LICENSE `_. +All usage and contributions to the project are subject to the terms and +conditions of this license. From 9a7d5e17d65cb142bdcace9dce3cb893b96f87f8 Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Sun, 4 Apr 2021 21:56:40 -0500 Subject: [PATCH 11/26] Add a hack to fix a doxyrest issue. --- docs/CMakeLists.txt | 6 +++++- docs/conf.in | 7 +++++++ 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 2fe505bd76..cd9a16baf0 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -47,6 +47,11 @@ function(_setup_doxyrest) set(DOXYREST_OUTPUT_DIR_NAME dpctl-capi-doxyrest) 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) @@ -81,7 +86,6 @@ function(_setup_sphinx) 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 diff --git a/docs/conf.in b/docs/conf.in index dcb3a2915e..c9c1964d76 100644 --- a/docs/conf.in +++ b/docs/conf.in @@ -47,6 +47,13 @@ if use_doxyrest == "ON": os.path.abspath("@DOXYREST_SPHINX_DIR@"), ) extensions += ["doxyrest", "cpplexer"] + # A workaround to fix issues leftover in the doxyrest generated + # rst files. + import fileinput + + with fileinput.FileInput("@DOXYREST_OUTPUT_DIR@/global.rst", inplace=True) as file: + for line in file: + print(line.replace("typedefDPCTL_C_EXTERN_C_BEGIN", ""), end="") # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] From 74d1c677390cf8103dea87576bfe3acdd8292a2f Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Sun, 4 Apr 2021 22:59:32 -0500 Subject: [PATCH 12/26] Fix version. --- docs/CMakeLists.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index cd9a16baf0..1722f98c51 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -138,7 +138,7 @@ function(_setup_sphinx) endfunction() function(_set_current_release) - set(CURRENT_RELEASE "") + set(CURRENT_RELEASE "" PARENT_SCOPE) # Use git describe to get latest tag name if (GIT_FOUND) execute_process( @@ -155,7 +155,7 @@ function(_set_current_release) OUTPUT_STRIP_TRAILING_WHITESPACE ) if (NOT "${CURRENT_RELEASE}" STREQUAL "${CURRENT_COMMIT}") - set(CURRENT_RELEASE "master") + set(CURRENT_RELEASE "master" PARENT_SCOPE) endif () endif (GIT_FOUND) endfunction() From 6d328be88066feb126c0b2ef153ad64c23339563 Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Sun, 4 Apr 2021 23:23:11 -0500 Subject: [PATCH 13/26] One more fix. --- docs/CMakeLists.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 1722f98c51..e810d2dc5a 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -157,6 +157,7 @@ function(_set_current_release) if (NOT "${CURRENT_RELEASE}" STREQUAL "${CURRENT_COMMIT}") set(CURRENT_RELEASE "master" PARENT_SCOPE) endif () + set(CURRENT_RELEASE ${CURRENT_RELEASE} PARENT_SCOPE) endif (GIT_FOUND) endfunction() From 522cc6cffed412608e6ccc5879a67b377e48df1d Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Mon, 5 Apr 2021 21:54:57 -0500 Subject: [PATCH 14/26] clean ups... --- docs/CMakeLists.txt | 2 +- docs/docfiles/toc_pyapi.rst | 11 ----------- docs/index_doxyrest.rst.in | 2 +- docs/index_no_doxyrest.rst.in | 2 +- 4 files changed, 3 insertions(+), 14 deletions(-) delete mode 100644 docs/docfiles/toc_pyapi.rst diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index e810d2dc5a..276f3ad0ed 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -155,7 +155,7 @@ function(_set_current_release) OUTPUT_STRIP_TRAILING_WHITESPACE ) if (NOT "${CURRENT_RELEASE}" STREQUAL "${CURRENT_COMMIT}") - set(CURRENT_RELEASE "master" PARENT_SCOPE) + set(CURRENT_RELEASE "master") endif () set(CURRENT_RELEASE ${CURRENT_RELEASE} PARENT_SCOPE) endif (GIT_FOUND) diff --git a/docs/docfiles/toc_pyapi.rst b/docs/docfiles/toc_pyapi.rst deleted file mode 100644 index 50ccd6cfcc..0000000000 --- a/docs/docfiles/toc_pyapi.rst +++ /dev/null @@ -1,11 +0,0 @@ -dpctl Python API -================ - -.. toctree:: - :hidden: - - dpctl - SYCL runtime wrapper classes and queue manager - dpctl.dptensor - Data-parallel tensor containers - dpctl.memory - USM memory manager - dpctl.program - Program manager - diff --git a/docs/index_doxyrest.rst.in b/docs/index_doxyrest.rst.in index c08594df1b..a432a685cd 100644 --- a/docs/index_doxyrest.rst.in +++ b/docs/index_doxyrest.rst.in @@ -9,7 +9,7 @@ :maxdepth: 1 :caption: API Documentation - docfiles/toc_pyapi + docfiles/dpctl_pyapi @DOXYREST_OUTPUT_DIR_NAME@/index .. include:: ./docfiles/boilerplate.rst diff --git a/docs/index_no_doxyrest.rst.in b/docs/index_no_doxyrest.rst.in index 3a624d2632..75e1dfef09 100644 --- a/docs/index_no_doxyrest.rst.in +++ b/docs/index_no_doxyrest.rst.in @@ -9,6 +9,6 @@ :maxdepth: 1 :caption: API Documentation - docfiles/toc_pyapi + docfiles/dpctl_pyapi .. include:: ./docfiles/boilerplate.rst From 1edef71ae9967ea2603b4ac11ce1187427c99a2e Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Tue, 6 Apr 2021 17:44:09 -0500 Subject: [PATCH 15/26] Add a quickstart guide. --- docs/docfiles/dpctl.dptensor_api.rst | 6 +- docs/docfiles/dpctl.memory_api.rst | 6 +- docs/docfiles/dpctl.program_api.rst | 6 +- docs/docfiles/dpctl_pyapi.rst | 10 + docs/docfiles/intro.rst | 27 +-- docs/docfiles/user_guides/QuickStart.rst | 257 +++++++++++++++++++++++ docs/index_doxyrest.rst.in | 5 + docs/index_no_doxyrest.rst.in | 6 + 8 files changed, 291 insertions(+), 32 deletions(-) create mode 100644 docs/docfiles/user_guides/QuickStart.rst diff --git a/docs/docfiles/dpctl.dptensor_api.rst b/docs/docfiles/dpctl.dptensor_api.rst index 7a3b571bd6..201bcf178d 100644 --- a/docs/docfiles/dpctl.dptensor_api.rst +++ b/docs/docfiles/dpctl.dptensor_api.rst @@ -1,8 +1,8 @@ .. _dpctl.dptensor_api: -######################### -dpctl dptensor Python API -######################### +############## +dpctl.dptensor +############## .. automodule:: dpctl.dptensor :members: diff --git a/docs/docfiles/dpctl.memory_api.rst b/docs/docfiles/dpctl.memory_api.rst index 1a0d4d6f72..4aac6e1c95 100644 --- a/docs/docfiles/dpctl.memory_api.rst +++ b/docs/docfiles/dpctl.memory_api.rst @@ -1,8 +1,8 @@ .. _dpctl.memory_api: -####################### -dpctl Memory Python API -####################### +############ +dpctl.memory +############ .. automodule:: dpctl.memory diff --git a/docs/docfiles/dpctl.program_api.rst b/docs/docfiles/dpctl.program_api.rst index 640fafe525..64db9c55e4 100644 --- a/docs/docfiles/dpctl.program_api.rst +++ b/docs/docfiles/dpctl.program_api.rst @@ -1,8 +1,8 @@ .. _dpctl.program_api: -######################## -dpctl Program Python API -######################## +############# +dpctl.program +############# .. automodule:: dpctl.program diff --git a/docs/docfiles/dpctl_pyapi.rst b/docs/docfiles/dpctl_pyapi.rst index dba5c7d6ff..3a4b20bc6a 100644 --- a/docs/docfiles/dpctl_pyapi.rst +++ b/docs/docfiles/dpctl_pyapi.rst @@ -6,6 +6,16 @@ dpctl Python API .. automodule:: dpctl +Sub-modules +----------- + +.. toctree:: + :maxdepth: 1 + + dpctl.dptensor_api + dpctl.memory_api + dpctl.program_api + Classes ------- diff --git a/docs/docfiles/intro.rst b/docs/docfiles/intro.rst index 8da8cddd8d..88be23bc35 100644 --- a/docs/docfiles/intro.rst +++ b/docs/docfiles/intro.rst @@ -4,27 +4,8 @@ Welcome to Data-parallel Control (dpctl)'s documentation! Data-parallel control (dpctl) is a library that exposes SYCL and DPCPP to languages other than C++. Currently, dpctl provides SYCL bindings for C and Python making it possible to access SYCL runtime objects and methods from these -languages. The SYCL functionality covered by dpctl includes the core SYCL -runtime classes described in Section 4.6 of the -`SYCL 2020 spec `_ -and USM memory management. dpctl also has experimental support for SYCL's +languages. The SYCL functionality covered by dpctl includes the core SYCL +runtime classes described in Section 4.6 of the +`SYCL 2020 spec `_ +and USM memory management. dpctl also has experimental support for SYCL's ``kernel`` and ``program`` classes. - -Core Features -------------- - -.. todo:: - - Coming soon. - -User Guidies ------------- - -.. todo:: - - Device Management. - -.. todo:: - - USM Memory Management - diff --git a/docs/docfiles/user_guides/QuickStart.rst b/docs/docfiles/user_guides/QuickStart.rst new file mode 100644 index 0000000000..b880d98bda --- /dev/null +++ b/docs/docfiles/user_guides/QuickStart.rst @@ -0,0 +1,257 @@ +.. _quick_start_guide: + +################# +Quick Start Guide +################# + + +.. contents:: Table of contents + :local: + :backlinks: none + :depth: 3 + +Installing from oneAPI +---------------------- + +Dpctl is available as part of the oneAPI Intel Distribution of Python (IDP). +Please follow `oneAPI installation guide`_ to install oneAPI. In this guide it +is assumed oneAPI is installed in the standard location and the environment +variable ``ONEAPI_ROOT`` points to the following installation root directory: + + - Windows: ``C:\Program Files (x86)\Intel\oneAPI\`` + - Linux: ``/opt/intel/oneapi`` + +Once oneAPI is installed, dpctl is ready to be used by setting up the IDP that +is available inside oneAPI. IDP can be set up as follows: + +On Linux + +.. code-block:: bash + + source ${ONEAPI_ROOT}/intelpython/latest/env/vars.sh + python -c "import dpctl; dpctl.lsplatform()" + +On Windows + +.. code-block:: bat + + call "%ONEAPI_ROOT%\intelpython\latest\env\vars.bat" + python -c "import dpctl; dpctl.lsplatform()" + + +.. note:: + + The ``dpctl.lsplatform()`` function is new in dpctl 0.7 and will be + available in oneAPI 2021.3. If you are following the guide on an older + oneAPI installation, use ``dpctl.dump()``. If no GPU platforms are shown, + make source your system has a GPU and has the necessary GPU drivers. You can + install GPU drivers by following the `GPU driver installation guide`_. + +Install Wheel package from Pypi +------------------------------- + +1. Install dpctl + +.. code-block:: bash + + python -m pip install --index-url https://pypi.anaconda.org/intel/simple -extra-index-url https://pypi.org/simple dpctl + +.. note:: + + Dpctl wheel package is placed on Pypi, but some of its dependencies + (like Intel numpy) are available only in Anaconda Cloud. That is why install + command requires additional intel Pypi channel from Anaconda Cloud. + +2. Set path to Performance Libraries in case of using ``venv`` or system Python. + + +On Linux: + +.. code-block:: bash + + export LD_LIBRARY_PATH=/lib + +On Windows: + +.. code-block:: bat + + set PATH=\bin;\Library\bin;%PATH% + +Building from source +-------------------- + +To build dpctl from source, we need dpcpp and GPU drivers (and optionally CPU +OpenCL drivers). It is preferable to use the dpcpp compiler packaged as part of +oneAPI. However, it is possible to use a custom build of dpcpp and use that to +build dpctl, especially if you want to enable CUDA support. + +Building using oneAPI dpcpp +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As before, oneAPI and graphics drivers should be installed on the system prior +to proceeding further. + +**Activate oneAPI as follows** + +On Linux + +.. code-block:: bash + + source ${ONEAPI_ROOT}/setvars.sh + +On Windows + +.. code-block:: bat + + call "%ONEAPI_ROOT%\setvars.bat" + +**Build and install using conda-build** + +The conda-recipe included with the sources can be used to build the dpctl +package. The advantage of this approach is that all dependencies are pulled in +from oneAPI's intelpython conda channel that was installed as part of oneAPI. + +.. code-block:: bash + + export ONEAPI_ROOT=/opt/intel/oneapi + conda build conda-recipe -c ${ONEAPI_ROOT}/conda_channel + +On Windows to cope with `long file names `_, +use ``croot`` with short folder path: + +.. code-block:: bat + + set "ONEAPI_ROOT=C:\Program Files (x86)\Intel\oneAPI\" + conda build --croot=C:/tmp conda-recipe -c "%ONEAPI_ROOT%\conda_channel" + +After building the conda package you may install it by executing: + +.. code-block:: bash + + conda install dpctl + +.. note:: + + You could face issues with conda-build version 3.20. Use conda-build + 3.18 instead. + +**Build and Install with setuptools** + +To build using Python ``setuptools``, the following packages should be +installed: + + - ``cython`` + - ``numpy`` + - ``cmake`` + - ``ninja`` (only on Windows) + - ``gtest`` (optional to run C API tests) + - ``pytest`` (optional to run Python API tests) + +Once the prerequisites are installed, building using ``setuptools`` involves The +usual steps: + +to build and install. + +.. code-block:: bash + + python setup.py install + +to develop. + +.. code-block:: bash + + python setup.py develop + +Building using custom dpcpp +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. todo: + + Instructions coming soon. + +Using dpctl +----------- + +Dpctl requires a DPC++ runtime. When dpctl is installed via conda then it uses +the DPC++ runtime from ``dpcpp_cpp_rt`` package that is part of IDP. When using +``setuptools`` make sure a compatible version of DPC++ runtime is available on +the system. The easiest way to setup a DPC++ runtime will be by activating +oneAPI. + +Running examples and tests +-------------------------- + +Running the examples +~~~~~~~~~~~~~~~~~~~~ + +After setting up dpctl you can try out the Python examples as follows: + +.. code-block:: bash + + for script in `ls examples/python/` + do + echo "executing ${script}" + python examples/python/${script} + done + +The dpctl repository also provides a set of examples of building Cython +extensions with DPC++ compiler, that interoperate with dpctl. These examples are +located under *examples/cython*. Each example in the folder can be built using +``CC=clang CXX=dpcpp python setup.py build_ext --inplace``. Please refer to +``run.py`` script in respective folders to execute the Cython extension +examples. + +Running the Python tests +~~~~~~~~~~~~~~~~~~~~~~~~ + +The dpctl Python test suite can be executed as follows: + +.. code-block:: bash + + pytest --pyargs dpctl + + +Building the C API shared library +--------------------------------- + +The dpctl C API is a shared library called libDPCTLSyclInterface and is built +together when build the Python package. However, it is possible to only build +the C API as a standalone library. To do so, you will need ``cmake``, +``ninja`` or ``make``, and optionally ``gtest 1.10`` if you wish to run the +C API test suite. + +For example, on Linux the following script can be used to build the C oneAPI +library. + +.. code-block:: bash + + #!/bin/bash + set +xe + rm -rf build + mkdir build + pushd build + + INSTALL_PREFIX=`pwd`/../install + rm -rf ${INSTALL_PREFIX} + export ONEAPI_ROOT=/opt/intel/oneapi + DPCPP_ROOT=${ONEAPI_ROOT}/compiler/latest/linux + + cmake \ + -DCMAKE_BUILD_TYPE=Release \ + -DCMAKE_INSTALL_PREFIX=${INSTALL_PREFIX} \ + -DCMAKE_PREFIX_PATH=${INSTALL_PREFIX} \ + -DDPCPP_INSTALL_DIR=${DPCPP_ROOT} \ + -DCMAKE_C_COMPILER:PATH=${DPCPP_ROOT}/bin/clang \ + -DCMAKE_CXX_COMPILER:PATH=${DPCPP_ROOT}/bin/dpcpp \ + -DDPCTL_ENABLE_LO_PROGRAM_CREATION=ON \ + -DDPCTL_BUILD_CAPI_TESTS=ON \ + .. + + make V=1 -n -j 4 && make check && make install + + + + + +.. _oneAPI installation guide: https://software.intel.com/content/www/us/en/develop/articles/installation-guide-for-intel-oneapi-toolkits.html +.. _GPU driver installation guide : https://dgpu-docs.intel.com/installation-guides/index.html diff --git a/docs/index_doxyrest.rst.in b/docs/index_doxyrest.rst.in index a432a685cd..f870816ce8 100644 --- a/docs/index_doxyrest.rst.in +++ b/docs/index_doxyrest.rst.in @@ -5,6 +5,11 @@ .. include:: ./docfiles/intro.rst +.. toctree:: + :maxdepth: 1 + :caption: User Guides + + docfiles/user_guides/QuickStart .. toctree:: :maxdepth: 1 :caption: API Documentation diff --git a/docs/index_no_doxyrest.rst.in b/docs/index_no_doxyrest.rst.in index 75e1dfef09..85be19b4b0 100644 --- a/docs/index_no_doxyrest.rst.in +++ b/docs/index_no_doxyrest.rst.in @@ -5,6 +5,12 @@ .. include:: ./docfiles/intro.rst +.. toctree:: + :maxdepth: 1 + :caption: User Guides + + docfiles/user_guides/QuickStart + .. toctree:: :maxdepth: 1 :caption: API Documentation From ad56e4a1b5b923414f5882afe0e0edfc8aacad16 Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Tue, 6 Apr 2021 22:04:00 -0500 Subject: [PATCH 16/26] Merge master and add version support. --- docs/CMakeLists.txt | 7 +++++++ docs/_templates/versions.html | 22 ++++++++++++++++++++++ docs/conf.in | 28 ++++++++++++++++++++++++++++ docs/doc_versions.txt | 2 ++ docs/docfiles/intro.rst | 22 ++++++++++++++-------- 5 files changed, 73 insertions(+), 8 deletions(-) create mode 100644 docs/_templates/versions.html create mode 100644 docs/doc_versions.txt diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 276f3ad0ed..fa92634608 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -7,6 +7,13 @@ option(DPCTL_ENABLE_DOXYREST 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 diff --git a/docs/_templates/versions.html b/docs/_templates/versions.html new file mode 100644 index 0000000000..623bf289d5 --- /dev/null +++ b/docs/_templates/versions.html @@ -0,0 +1,22 @@ +{% if READTHEDOCS or display_lower_left %} +{# Add rst-badge after rst-versions for small badge style. #} +
+ + Other versions + v: {{ current_version }} + + +
+ {% if versions|length >= 1 %} +
+
{{ _('Versions') }}
+ {% for slug, url in versions %} + {% if slug == current_version %} {% endif %} +
{{ slug }}
+ {% if slug == current_version %} {% endif %} + {% endfor %} +
+ {% endif %} +
+
+{% endif %} diff --git a/docs/conf.in b/docs/conf.in index c9c1964d76..87185dff79 100644 --- a/docs/conf.in +++ b/docs/conf.in @@ -99,3 +99,31 @@ html_theme_options = { # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". # html_static_path = ['_static'] + +generate_multiversion = "@DPCTL_USE_MULTIVERSION_TEMPLATE@" + +if generate_multiversion == "ON": + try: + html_context + except NameError: + html_context = dict() + html_context["display_lower_left"] = True + templates_path = ["_templates"] + html_context["current_version"] = version + html_context["version"] = version + + # POPULATE LINKS TO OTHER VERSIONS + html_context["versions"] = list() + + # Populate the list of documented versions from the doc_versions.tx + versions = [] + with open("doc_versions.txt", "r") as doc_versions: + while True: + version = doc_versions.readline().strip() + if not version: + break + elif len(version): + versions.append(version) + + for version in versions: + html_context["versions"].append((version, "../" + version + "/index.html")) diff --git a/docs/doc_versions.txt b/docs/doc_versions.txt new file mode 100644 index 0000000000..a574472667 --- /dev/null +++ b/docs/doc_versions.txt @@ -0,0 +1,2 @@ +0.6.1 +latest \ No newline at end of file diff --git a/docs/docfiles/intro.rst b/docs/docfiles/intro.rst index 88be23bc35..115749b3da 100644 --- a/docs/docfiles/intro.rst +++ b/docs/docfiles/intro.rst @@ -1,11 +1,17 @@ Welcome to Data-parallel Control (dpctl)'s documentation! ========================================================= -Data-parallel control (dpctl) is a library that exposes SYCL and DPCPP to -languages other than C++. Currently, dpctl provides SYCL bindings for C and -Python making it possible to access SYCL runtime objects and methods from these -languages. The SYCL functionality covered by dpctl includes the core SYCL -runtime classes described in Section 4.6 of the -`SYCL 2020 spec `_ -and USM memory management. dpctl also has experimental support for SYCL's -``kernel`` and ``program`` classes. +The data-parallel control (dpctl) library provides C and Python bindings for +`SYCL 2020 `_. +The SYCL 2020 features supported by dpctl are limited to those included by +Intel's DPCPP compiler and specifically cover the SYCL runtime classes described +in `Section 4.6 `_ +of the SYCL 2020 specification. Apart from the bindings for these runtime +classes, dpctl includes bindings for SYCL USM memory allocators and +deallocators. Dpctl's Python API provides classes that implement +`Python buffer protocol `_ +using SYCL USM memory; making it possible to create Python objects that are +backed by SYCL USM memory. + +Dpctl also supports the DPCPP ``ONEAPI::filter_selector`` extension and has +experimental support for SYCL's ``kernel`` and ``program`` classes. From 03b180ab7cb048ae5d03d56a3c9ae480a4b9519f Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Tue, 6 Apr 2021 22:58:25 -0500 Subject: [PATCH 17/26] Minor fixes... --- docs/Doxyfile.in | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index bc6fdc3b22..4d4a2a6de9 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -937,7 +937,7 @@ EXCLUDE_SYMLINKS = NO # Note that the wildcards are matched against the file with absolute path, so to # exclude all test directories for example use the pattern */test/* -EXCLUDE_PATTERNS = +EXCLUDE_PATTERNS = # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names # (namespaces, classes, functions, etc.) that should be excluded from the From a9fe02695af1603e958df582dfa98886548e2f24 Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Tue, 6 Apr 2021 23:32:29 -0500 Subject: [PATCH 18/26] Add a hard coded link to our doc site. --- docs/conf.in | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/conf.in b/docs/conf.in index 87185dff79..911a7f47ea 100644 --- a/docs/conf.in +++ b/docs/conf.in @@ -125,5 +125,10 @@ if generate_multiversion == "ON": elif len(version): versions.append(version) + # FIXME: Remove this hard coding + DOC_SITE_NAME = "https://intelpython.github.io/dpctl/" + for version in versions: - html_context["versions"].append((version, "../" + version + "/index.html")) + html_context["versions"].append( + (version, DOC_SITE_NAME + version + "/index.html") + ) From 60ca36031f4d57670d62be733bcb7d30493c4094 Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Wed, 7 Apr 2021 00:03:20 -0500 Subject: [PATCH 19/26] Fix weird punctuations. --- docs/docfiles/user_guides/QuickStart.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docfiles/user_guides/QuickStart.rst b/docs/docfiles/user_guides/QuickStart.rst index b880d98bda..3e4d0b49b9 100644 --- a/docs/docfiles/user_guides/QuickStart.rst +++ b/docs/docfiles/user_guides/QuickStart.rst @@ -65,13 +65,13 @@ Install Wheel package from Pypi 2. Set path to Performance Libraries in case of using ``venv`` or system Python. -On Linux: +On Linux .. code-block:: bash export LD_LIBRARY_PATH=/lib -On Windows: +On Windows .. code-block:: bat @@ -148,15 +148,15 @@ installed: - ``pytest`` (optional to run Python API tests) Once the prerequisites are installed, building using ``setuptools`` involves The -usual steps: +usual steps -to build and install. +to build and install .. code-block:: bash python setup.py install -to develop. +, and to develop. .. code-block:: bash From 0901f9d6b8a24fc3e5bfcbc16c52bbc7ff599a1e Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Mon, 12 Apr 2021 17:41:23 -0500 Subject: [PATCH 20/26] Small change to where C API docs are generated. --- docs/CMakeLists.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index fa92634608..31593dbda6 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -51,7 +51,7 @@ function(_setup_doxygen) endfunction() function(_setup_doxyrest) - set(DOXYREST_OUTPUT_DIR_NAME dpctl-capi-doxyrest) + set(DOXYREST_OUTPUT_DIR_NAME docfiles/dpctl-capi) set(DOXYREST_OUTPUT_DIR ${CMAKE_CURRENT_SOURCE_DIR}/${DOXYREST_OUTPUT_DIR_NAME} PARENT_SCOPE From c444c3830c61d95f3c99a4ba71488d983b2c6813 Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Tue, 13 Apr 2021 09:47:50 -0500 Subject: [PATCH 21/26] Update gitignore --- docs/.gitignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/.gitignore b/docs/.gitignore index eab5cd6f4e..c7b38c7ac8 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,6 +1,6 @@ docs generated_docs -dpctl-capi-doxyrest +docfiles/dpctl-capi api build conf.py From 9f92c12c3573a8aa926af78642aa47fd479cfb6a Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Tue, 13 Apr 2021 21:45:57 -0500 Subject: [PATCH 22/26] Add more members to documentation for SyclContext. --- docs/docfiles/dpctl_pyapi/SyclContext.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/docfiles/dpctl_pyapi/SyclContext.rst b/docs/docfiles/dpctl_pyapi/SyclContext.rst index 4620a73b9e..190223bf5a 100644 --- a/docs/docfiles/dpctl_pyapi/SyclContext.rst +++ b/docs/docfiles/dpctl_pyapi/SyclContext.rst @@ -7,3 +7,5 @@ dpctl.SyclContext .. autoclass:: dpctl.SyclContext :members: :undoc-members: + :special-members: __name__, __repr__ + :private-members: _get_capsule From e63a473e8ae7c5c2d6084091af56133c80328372 Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Tue, 13 Apr 2021 22:38:25 -0500 Subject: [PATCH 23/26] Show todo sections. --- docs/conf.in | 2 +- docs/docfiles/user_guides/QuickStart.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/conf.in b/docs/conf.in index 911a7f47ea..445c0ddf20 100644 --- a/docs/conf.in +++ b/docs/conf.in @@ -33,9 +33,9 @@ extensions = [ "sphinx.ext.githubpages", "sphinx.ext.autodoc", "sphinx.ext.napoleon", - "sphinx.ext.todo", ] +todo_include_todos = True use_doxyrest = "@DPCTL_ENABLE_DOXYREST@" if use_doxyrest == "ON": diff --git a/docs/docfiles/user_guides/QuickStart.rst b/docs/docfiles/user_guides/QuickStart.rst index 3e4d0b49b9..ad0c90e509 100644 --- a/docs/docfiles/user_guides/QuickStart.rst +++ b/docs/docfiles/user_guides/QuickStart.rst @@ -165,7 +165,7 @@ to build and install Building using custom dpcpp ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. todo: +.. todo:: Instructions coming soon. From 03b020e098bf4a6d36ae416ea989e2590edef094 Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Sat, 17 Apr 2021 23:30:44 -0500 Subject: [PATCH 24/26] Revert superfluous change. --- dpctl/_sycl_device.pyx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/dpctl/_sycl_device.pyx b/dpctl/_sycl_device.pyx index 6dda293f87..5209cad9f1 100644 --- a/dpctl/_sycl_device.pyx +++ b/dpctl/_sycl_device.pyx @@ -17,8 +17,7 @@ # distutils: language = c++ # cython: language_level=3 -""" - Implements SyclDevice Cython extension type. +""" Implements SyclDevice Cython extension type. """ from ._backend cimport ( From 09d3f55338a9577f54ab7d388d8fbd50b223c3d4 Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Sat, 17 Apr 2021 23:31:50 -0500 Subject: [PATCH 25/26] Revert one more superfluous change. --- dpctl/_sycl_device.pyx | 1 + 1 file changed, 1 insertion(+) diff --git a/dpctl/_sycl_device.pyx b/dpctl/_sycl_device.pyx index 5209cad9f1..a0f44569c0 100644 --- a/dpctl/_sycl_device.pyx +++ b/dpctl/_sycl_device.pyx @@ -184,6 +184,7 @@ cdef class SyclDevice(_SyclDevice): :func:`dpctl.select_gpu_device()`, :func:`dpctl.select_host_device()`. + :Example: .. code-block:: python From 0baa2f0f08effabb3baf24f451ec4b616ded0b1d Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Sun, 18 Apr 2021 22:55:14 -0500 Subject: [PATCH 26/26] Stylistic changes. --- docs/conf.in | 89 ++++++++++++++++++++++ docs/docfiles/dpctl_pyapi/SyclContext.rst | 34 ++++++++- docs/docfiles/dpctl_pyapi/SyclDevice.rst | 20 ++++- docs/docfiles/dpctl_pyapi/SyclPlatform.rst | 11 +++ docs/docfiles/dpctl_pyapi/SyclQueue.rst | 32 ++++++++ 5 files changed, 183 insertions(+), 3 deletions(-) diff --git a/docs/conf.in b/docs/conf.in index 445c0ddf20..e36c49c35c 100644 --- a/docs/conf.in +++ b/docs/conf.in @@ -32,6 +32,7 @@ extensions = [ "sphinx.ext.viewcode", "sphinx.ext.githubpages", "sphinx.ext.autodoc", + "sphinx.ext.autosummary", "sphinx.ext.napoleon", ] @@ -132,3 +133,91 @@ if generate_multiversion == "ON": html_context["versions"].append( (version, DOC_SITE_NAME + version + "/index.html") ) + + +from typing import Any, Optional, List, Tuple +from sphinx.ext.autodoc import ClassDocumenter, ObjectMembers +from sphinx.ext.autodoc.importer import get_class_members +import types + + +class ClassMembersDocumenter(ClassDocumenter): + """ + Documenter for only class members and skips the class and __init__ + docstrings. + """ + + objtype = "classmembers" + + def add_directive_header(self, sig: str) -> None: + pass + + def get_doc( + self, encoding: str = None, ignore: int = None + ) -> Optional[List[List[str]]]: + return None + + +# See https://stackoverflow.com/questions/20569011/python-sphinx-autosummary-automated-listing-of-member-functions +from sphinx.ext.autosummary import Autosummary +from sphinx.ext.autosummary import get_documenter +from docutils.parsers.rst import directives +from sphinx.util.inspect import safe_getattr + + +class AutoAutoSummary(Autosummary): + """Create a summary for methods and attributes (autosummary). + See https://stackoverflow.com/questions/20569011/python-sphinx-autosummary-automated-listing-of-member-functions + """ + + option_spec = { + "methods": directives.unchanged, + "private_methods": directives.unchanged, + "attributes": directives.unchanged, + } + + required_arguments = 1 + + @staticmethod + def get_members(app, obj, typ, include_public=None): + if not include_public: + include_public = [] + items = [] + for name in sorted(obj.__dict__.keys()): + try: + documenter = get_documenter(app, safe_getattr(obj, name), obj) + except AttributeError: + continue + if documenter.objtype in typ: + items.append(name) + return items + + def run(self): + clazz = str(self.arguments[0]) + (module_name, class_name) = clazz.rsplit(".", 1) + m = __import__(module_name, globals(), locals(), [class_name]) + c = getattr(m, class_name) + app = self.state.document.settings.env.app + if "methods" in self.options: + methods = self.get_members(app, c, ["method"], ["__init__"]) + self.content = [ + "%s" % method for method in methods if not method.startswith("_") + ] + if "private_methods" in self.options: + private_methods = self.get_members(app, c, ["method"], ["__init__"]) + self.content = [ + "%s" % method + for method in private_methods + if method.startswith("_") and not method.startswith("__") + ] + if "attributes" in self.options: + attribs = self.get_members(app, c, ["attribute", "property"]) + self.content = [ + "%s" % attrib for attrib in attribs if not attrib.startswith("_") + ] + return super().run() + + +def setup(app): + app.add_directive("autoautosummary", AutoAutoSummary) + app.add_autodocumenter(ClassMembersDocumenter) diff --git a/docs/docfiles/dpctl_pyapi/SyclContext.rst b/docs/docfiles/dpctl_pyapi/SyclContext.rst index 190223bf5a..64f27c382a 100644 --- a/docs/docfiles/dpctl_pyapi/SyclContext.rst +++ b/docs/docfiles/dpctl_pyapi/SyclContext.rst @@ -5,7 +5,37 @@ dpctl.SyclContext ################# .. autoclass:: dpctl.SyclContext + + .. rubric:: Attributes: + + .. autoautosummary:: dpctl.SyclContext + :attributes: + + .. rubric:: Private methods: + + .. autoautosummary:: dpctl.SyclContext + :private_methods: + + .. rubric:: Public methods: + + .. autoautosummary:: dpctl.SyclContext + :methods: + +Detail +====== + +Private methods +--------------- + +.. autoclassmembers:: dpctl.SyclContext + :noindex: + :private-members: _get_capsule + + +Public methods +-------------- + +.. autoclassmembers:: dpctl.SyclContext + :noindex: :members: :undoc-members: - :special-members: __name__, __repr__ - :private-members: _get_capsule diff --git a/docs/docfiles/dpctl_pyapi/SyclDevice.rst b/docs/docfiles/dpctl_pyapi/SyclDevice.rst index 6ca34f70d8..259153db50 100644 --- a/docs/docfiles/dpctl_pyapi/SyclDevice.rst +++ b/docs/docfiles/dpctl_pyapi/SyclDevice.rst @@ -5,6 +5,24 @@ dpctl.SyclDevice ################ .. autoclass:: dpctl.SyclDevice + + .. rubric:: Attributes: + + .. autoautosummary:: dpctl.SyclDevice + :attributes: + + .. rubric:: Public methods: + + .. autoautosummary:: dpctl.SyclDevice + :methods: + +Detail +====== + +Public methods +-------------- + +.. autoclassmembers:: dpctl.SyclDevice + :noindex: :members: - :inherited-members: :undoc-members: diff --git a/docs/docfiles/dpctl_pyapi/SyclPlatform.rst b/docs/docfiles/dpctl_pyapi/SyclPlatform.rst index ee6f0c95c2..583c24ab4c 100644 --- a/docs/docfiles/dpctl_pyapi/SyclPlatform.rst +++ b/docs/docfiles/dpctl_pyapi/SyclPlatform.rst @@ -4,6 +4,17 @@ dpctl.SyclPlatform ################## + .. autoclass:: dpctl.SyclPlatform + + +Detail +====== + +Public methods +-------------- + +.. autoclassmembers:: dpctl.SyclPlatform + :noindex: :members: :undoc-members: diff --git a/docs/docfiles/dpctl_pyapi/SyclQueue.rst b/docs/docfiles/dpctl_pyapi/SyclQueue.rst index 75990eb215..84cc6f7740 100644 --- a/docs/docfiles/dpctl_pyapi/SyclQueue.rst +++ b/docs/docfiles/dpctl_pyapi/SyclQueue.rst @@ -5,5 +5,37 @@ dpctl.SyclQueue ############### .. autoclass:: dpctl.SyclQueue + + .. rubric:: Attributes: + + .. autoautosummary:: dpctl.SyclQueue + :attributes: + + .. rubric:: Private methods: + + .. autoautosummary:: dpctl.SyclQueue + :private_methods: + + .. rubric:: Public methods: + + .. autoautosummary:: dpctl.SyclQueue + :methods: + +Detail +====== + +Private methods +--------------- + +.. autoclassmembers:: dpctl.SyclQueue + :noindex: + :private-members: _get_capsule + + +Public methods +-------------- + +.. autoclassmembers:: dpctl.SyclQueue + :noindex: :members: :undoc-members: