Add developer guide in docs

docs/CMakeLists.txt

@@ -8,8 +8,9 @@
 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)
+file(GLOB_RECURSE ${PROJECT_NAME}_PUBLIC_HEADERS ${PROJECT_SOURCE_DIR}/common/src/*.hpp
+     ${PROJECT_SOURCE_DIR}/fft/src/*.hpp
+)
 
 set(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR}/fft/src/)
 set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
@@ -21,15 +22,17 @@ set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
 configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT})
 
 # Doxygen won't create this for us
-file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR}) 
+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")
+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})
@@ -39,18 +42,19 @@ set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/sphinx)
 set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html)
 
 # Only regenerate Sphinx when:
-#  - Doxygen has rerun 
+#  - 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")
+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})
+install(DIRECTORY ${SPHINX_BUILD} DESTINATION ${CMAKE_INSTALL_DOCDIR})

docs/developer/CI.rst

@@ -0,0 +1,152 @@
+.. SPDX-FileCopyrightText: (C) The kokkos-fft development team, see COPYRIGHT.md file
+..
+.. SPDX-License-Identifier: MIT OR Apache-2.0 WITH LLVM-exception
+
+CI (Continuous Integration)
+===========================
+
+Our CI system is designed to automate testing and ensure that every change meets our coding styles. 
+If you are familiar with github actions, you may find our workflow `here <https://github.com/kokkos/kokkos-fft/blob/main/.github/workflows/build_test.yaml>`_.
+The CI process includes:
+
+- **Linting and Style Checks:** Verifying that the code follows to our style guidelines.
+- **Build Verification:** Compiling and installing the project in various environments to ensure compatibility.
+- **Unit tests:** Running unit tests on CPUs (on github Azure) and NVIDIA GPUs (on our local server).
+
+Linting and Style Checks
+------------------------
+
+We have four CIs for formatting: ``reuse``, ``clang-format``, ``cmake-format`` and ``typos``. 
+
+#. **License Check with Reuse:**  
+   All the files in the repo need to include copyright and license information at the top.
+   These are automatically confirmed with `REUSE compliance check <https://reuse.software>`_ in CI.
+   If there is a file without the copyright, the REUSE CI will fail and notify which file misses a copyright.
+   The copyright statement in ``CMakeLists.txt`` is given in the following manner.
+
+   .. code-block:: CMake
+
+     # SPDX-FileCopyrightText: (C) The kokkos-fft development team, see COPYRIGHT.md files
+     #
+     # SPDX-License-Identifier: MIT OR Apache-2.0 WITH LLVM-exception
+
+     cmake_minimum_required(VERSION 3.22)
+
+#. **Code formatting with clang-format:**  
+   All the source codes (``.cpp`` and ``.hpp`` files) in the repo shall be formatted with clang-format 17.
+   To format a C++ file, please apply the following command
+
+   .. code-block:: bash
+
+      clang-format -i <cppfile_you_have_modified>
+
+   Format are automatically confirmed with `clang-format check <https://clang.llvm.org/docs/ClangFormat.html>`_ in CI.
+   If further formatting is needed, the clang-format CI will fail and notify which file needs to be modified.
+
+#. **CMake formatting with cmake-format:**  
+   All the CMake files (``CMakeLists.txt`` and ``.cmake`` files) in the repo shall be formatted with cmake-format.
+   To format a CMake file, please apply the following command
+
+   .. code-block:: bash
+
+      cmake-format --in-place
+
+   Format are automatically confirmed with `cmake-format check <https://github.com/cheshirekow/cmake_format>`_ in CI.
+   If further formatting is needed, the cmake-format CI will fail and notify which file needs to be modified.
+
+#. **Spell check with typos:**  
+   Spell errors are checked with `typos <https://github.com/crate-ci/typos>`_ in CI.
+   If potential typos are detected, they will report typos with suggestions.
+
+Build Verification
+------------------
+
+Compilation tests are performed inside containers for each backend including NVIDIA, AMD and Intel GPUs
+(see `Dockerfiles <https://github.com/kokkos/kokkos-fft/tree/main/docker>`_).
+These images are useful to develop locally particularly when you are interested in modifying the
+backend specific codes. In other word, if you develop and test your code inside these containers, 
+your PR will likely to pass our CI. For each backend, we test to compile a simple test code by using kokkos-fft as CMake subdirectory or installed library. 
+
+Unit tests
+----------
+
+We rely on `googletest <https://github.com/google/googletest>`_ for unit-testing. For CPU backends, we perform unit-tests on github Azure. 
+We also perform unit-tests on NVIDIA GPUs in our local server, which requires a special approval from maintaniers.
+If you change the backend specific source codes for HIP or SYCL backends, please make sure that all the unit-tests pass.
+For Intel GPUs (Intel PVC), you can test locally in the following way.
+
+   .. code-block:: bash
+
+      cmake -B build \
+      -DCMAKE_CXX_COMPILER=icpx \
+      -DCMAKE_BUILD_TYPE=Release \
+      -DCMAKE_CXX_STANDARD=20 \
+      -DKokkos_ENABLE_SYCL=ON \
+      -DKokkos_ARCH_INTEL_PVC=ON \
+      -DKokkosFFT_ENABLE_INTERNAL_KOKKOS=ON \
+      -DKokkosFFT_ENABLE_TESTS=ON \
+      -DKokkosFFT_ENABLE_EXAMPLES=ON
+
+      cmake --build build -j 8
+      cd build && ctest --output-on-failure
+
+Here is the summary of our compile and run tests for each backend. For GPU backends, we compile with and without ``KokkosFFT_ENABLE_HOST_AND_DEVICE`` option (see :doc:`CMake options<../intro/building>`).
+
+.. list-table:: Test summary
+   :widths: 15 15 15 15 15 15
+   :header-rows: 1
+
+   * - build name
+     - Compiler, C++ standard
+     - Kokkos backend
+     - Description
+     - Build/install test
+     - Run test
+   * - clang-tidy
+     - clang, 17
+     - ``Kokkos_ENABLE_SERIAL``
+     - clang-tidy check
+     - x (Aazure)
+     - None
+   * - serial
+     - gcc, 17
+     - ``Kokkos_ENABLE_SERIAL``
+     -
+     - x (Aazure)
+     - x (Aazure)
+   * - threads
+     - gcc, 20
+     - ``Kokkos_ENABLE_THREADS``
+     -
+     - x (Aazure)
+     - x (Aazure)
+   * - openmp
+     - gcc, 17
+     - ``Kokkos_ENABLE_OPENMP``
+     - Debug mode
+     - x (Aazure)
+     - x (Aazure)
+   * - cuda
+     - gcc, 17
+     - ``Kokkos_ENABLE_CUDA``
+     -
+     - x (Aazure)
+     - x (self-hosted)
+   * - hip
+     - hipcc, 17
+     - ``Kokkos_ENABLE_HIP``
+     - ``hipfft`` backend
+     - x (Aazure)
+     - None
+   * - rocm
+     - hipcc, 20
+     - ``Kokkos_ENABLE_HIP``
+     - ``rocfft`` backend
+     - x (Aazure)
+     - None
+   * - sycl
+     - icpx, 17
+     - ``Kokkos_ENABLE_SYCL``
+     -
+     - x (Aazure)
+     - None

docs/developer/contributing.rst

@@ -0,0 +1,81 @@
+.. SPDX-FileCopyrightText: (C) The kokkos-fft development team, see COPYRIGHT.md file
+..
+.. SPDX-License-Identifier: MIT OR Apache-2.0 WITH LLVM-exception
+
+Contributing
+============
+
+We briefly explain the workflow to contribute by making a pull request (PR) against ``main`` branch.
+Followings are the steps to contribute the project:
+
+#. **Report bugs or Suggest features:**
+   First open issues or ask questions on the Kokkos slack channel.
+
+#. **Fork the Repository:**
+   Click the "Fork" button on our `repo <https://github.com/kokkos/kokkos-fft>`_ to create your own copy.
+
+#. **Clone Your Fork:**  
+   Clone the repository to your local machine with submodules.
+
+   .. code-block:: bash
+
+      git clone --recursive https://github.com/<your-username>/kokkos-fft.git
+
+#. **Add the Upstream Remote:**  
+   Set the original repository as the ``upstream`` remote to keep your fork up to date:
+
+   .. code-block:: bash
+
+      cd kokkos-fft
+      git remote add upstream https://github.com/kokkos/kokkos-fft.git   
+
+#. **Create a New Branch:**
+   Create a new branch for your feature or bug fix with a descriptive name:
+
+   .. code-block:: bash
+
+      git switch -c <feature-name>
+
+#. **Rebase Your Branch Against Upstream/main:**  
+   To ensure your branch is up to date with the latest changes from the original repository:
+
+   1. Fetch the latest changes from upstream:
+
+      .. code-block:: bash
+
+         git fetch upstream main
+
+   2. Rebase your branch onto the upstream ``main`` branch:
+
+      .. code-block:: bash
+
+         git rebase upstream/main
+
+#. **Make Your Changes:**  
+   Implement your feature or bug fix. Ensure you adhere to the project's coding standards and guidelines (see :doc:`details of CI<CI>`).
+
+#. **Commit Your Changes:**  
+   Stage your changes and commit them with a clear, concise commit message:
+
+   .. code-block:: bash
+
+      git add .
+      git commit -m "Brief description of changes"
+
+#. **Push Your Branch:**  
+   Push your branch to your GitHub fork:
+
+   .. code-block:: bash
+
+      git push --force-with-lease origin <feature-name>
+
+#. **Open a Pull Request:**  
+   On `GitHub <https://github.com/kokkos/kokkos-fft>`_, open a PR from your branch to the original repository's ``main`` branch.
+   Include a detailed description of your changes and reference any related issues.
+
+#. **Participate in the Code Review:**  
+   Respond to any feedback or questions from maintainers. To run unit-tests on GPUs, you need a special CI approval from maintainers.
+   Update your PR as needed until it meets the project requirements.
+
+#. **Merge Your Changes:**  
+   Once your pull request is approved, your changes will be merged into the main project. Thank you for your contribution!