Merge pull request #42 from CExA-project/add-doxygen

Add doxygen

.readthedocs.yaml

@@ -0,0 +1,24 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+   fail_on_warning: false
+
+python:
+   install:
+   - requirements: docs/requirements.txt
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+  apt_packages:
+    - git
+    - g++
+    - make

CMakeLists.txt

@@ -16,6 +16,7 @@ list(PREPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
 option(BUILD_EXAMPLES "Build KokkosFFT examples" ON)
 option(KokkosFFT_ENABLE_HOST_AND_DEVICE "Enable FFT on both host and device" OFF)
 option(KokkosFFT_INTERNAL_Kokkos "Build internal Kokkos instead of relying on external one" OFF)
+option(KokkosFFT_ENABLE_DOCS "Build KokkosFFT documentaion/website" OFF)
 option(KokkosFFT_ENABLE_BENCHMARK "Build benchmarks for KokkosFFT" OFF)
 
 # Version information
@@ -69,6 +70,13 @@ if(BUILD_TESTING)
     endif()
 endif()
 
+# Build documentation with Doxygen and Sphinx
+if(KokkosFFT_ENABLE_DOCS)
+    find_package(Doxygen REQUIRED)
+    find_package(Sphinx REQUIRED)
+    add_subdirectory(docs)
+endif()
+
 # Benchmark
 if(KokkosFFT_ENABLE_BENCHMARK)
     option(BENCHMARK_ENABLE_TESTING "Enable testing of the benchmark library." OFF)

README.md

@@ -1,11 +1,14 @@
 # kokkos-fft
 
 [![CI](https://github.com/CExA-project/kokkos-fft/actions/workflows/build_test.yaml/badge.svg)](https://github.com/CExA-project/kokkos-fft/actions)
+[![docs](https://readthedocs.org/projects/kokkosfft/badge/?version=latest)](https://kokkosfft.readthedocs.io/en/latest/?badge=latest)
 
 UNOFFICIAL FFT interfaces for Kokkos C++ Performance Portability Programming EcoSystem
 
 KokkosFFT implements local interfaces Kokkos and de facto standard FFT libraries, including [fftw](http://www.fftw.org), [cufft](https://developer.nvidia.com/cufft), [hipfft](https://github.com/ROCm/hipFFT), and [oneMKL](https://spec.oneapi.io/versions/latest/elements/oneMKL/source/index.html). "Local" means not using MPI, or running within a single MPI process without knowing about MPI. We are inclined to implement the [numpy.fft](https://numpy.org/doc/stable/reference/routines.fft.html)-like interfaces adapted for [Kokkos](https://github.com/kokkos/kokkos).
-A key concept is that "As easy as numpy, as fast as vendor libraries". Accordingly, our API follows the API by [numpy.fft](https://numpy.org/doc/stable/reference/routines.fft.html) with minor differences. A fft library dedicated to Kokkos Device backend (e.g. [cufft](https://developer.nvidia.com/cufft) for CUDA backend) is automatically used. If something is wrong with runtime values (say `View` extents), it will raise runtime errors (C++ exceptions or assertions). Here is an example for 1D real to complex transform with `rfft` in python and KokkosFFT.
+A key concept is that "As easy as numpy, as fast as vendor libraries". Accordingly, our API follows the API by [numpy.fft](https://numpy.org/doc/stable/reference/routines.fft.html) with minor differences. A fft library dedicated to Kokkos Device backend (e.g. [cufft](https://developer.nvidia.com/cufft) for CUDA backend) is automatically used. If something is wrong with runtime values (say `View` extents), it will raise runtime errors (C++ exceptions or assertions). See [documentations](https://kokkosfft.readthedocs.io/) for more information. 
+
+Here is an example for 1D real to complex transform with `rfft` in python and KokkosFFT.
 ```python3
 import numpy as np
 x = np.random.rand(4)

cmake/FindSphinx.cmake

@@ -0,0 +1,10 @@
+#Look for an executable called sphinx-build
+find_program(SPHINX_EXECUTABLE
+             NAMES sphinx-build
+             DOC "Path to sphinx-build executable")
+
+include(FindPackageHandleStandardArgs)
+#Handle standard arguments to find_package like REQUIRED and QUIET
+find_package_handle_standard_args(Sphinx
+                                  "Failed to find sphinx-build executable"
+                                  SPHINX_EXECUTABLE)

docs/CMakeLists.txt

@@ -0,0 +1,52 @@
+# source: https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/
+
+# Find all the public headers
+file(COPY ${CMAKE_CURRENT_SOURCE_DIR}/conf.py DESTINATION ${CMAKE_CURRENT_BINARY_DIR})
+file(COPY ${CMAKE_CURRENT_SOURCE_DIR}/index.rst DESTINATION ${CMAKE_CURRENT_BINARY_DIR})
+
+file(GLOB_RECURSE ${PROJECT_NAME}_PUBLIC_HEADERS
+	 ${PROJECT_SOURCE_DIR}/fft/src/*.hpp)
+
+set(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR}/fft/src/)
+set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_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)
+
+# Set the Doxygen input and output directories in the Doxyfile
+configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT})
+
+# Doxygen won't create this for us
+file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR}) 
+
+# Only regenerate Doxygen when the Doxyfile or public headers change
+add_custom_command(OUTPUT ${DOXYGEN_INDEX_FILE}
+		DEPENDS ${${PROJECT_NAME}_PUBLIC_HEADERS}
+        COMMAND ${DOXYGEN_EXECUTABLE} Doxyfile
+		WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+		MAIN_DEPENDENCY Doxyfile
+        COMMENT "Generating docs")
+
+# Nice named target so we can run the job easily
+add_custom_target(Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE})
+
+set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
+set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
+set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html)
+
+# Only regenerate Sphinx when:
+#  - Doxygen has rerun 
+#  - Our doc files have been updated
+#  - The Sphinx config has been updated
+add_custom_target(Sphinx ALL
+	COMMAND ${SPHINX_EXECUTABLE} -W --keep-going -b html
+	# Tell Breathe where to find the Doxygen output
+	-Dbreathe_projects.${PROJECT_NAME}=${DOXYGEN_OUTPUT_DIR}/xml
+	${SPHINX_SOURCE} ${SPHINX_BUILD}
+	WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+	DEPENDS Doxygen
+	COMMENT "Generating documentation with Sphinx")
+
+include(GNUInstallDirs)
+install(DIRECTORY ${SPHINX_BUILD}
+	DESTINATION ${CMAKE_INSTALL_DOCDIR})