Documentation

We deploy the Kokkos-FFT website on readthedocs. The API references are auto generated by doxygen to ensure that the API documentation is always up-to-date with the source code.

Documentation Structure

The project documentation is divided into several sections:

Documentation structure

Component	Detailed description
User Guides	Installation instructions and basic usage.
Developer Guides	Information for developers on how to contribute, set up the environment, and follow coding conventions.
API Reference	Automatically generated from the source code docstrings using breath.
examples	Minimum working examples of APIs.

Among these, we expect that API Reference is the most relevant to external contributors.

Development environment

Our documentation relies on doxygen, sphinx, breath and sphinx-rtd-theme packages. For linux and MacOS users, you can construct local development environment in the following way.

# For linux users
sudo apt-get install doxygen

### For MacOS users
###brew install doxygen

# Following are the same
pip install sphinx
pip install breathe
pip install sphinx-rtd-theme

API Reference

API reference is auto-generated from docstrings within the C++ source code. Thus, all APIs must to be documented with doxygen style docstrings. To ensure accuracy and consistency:

1. Write Clear and Consistent Docstrings: Use descriptive and clear docstrings for all APIs including functions and classes. Each docstring should include: - A brief description of the purpose. - Descriptions of parameters and return values.

   Here is an example of docstrings for a function (rendered version is found here).

   /// \brief Return the DFT sample frequencies
   ///
   /// \tparam ExecutionSpace: The type of Kokkos execution space
   /// \tparam RealType: The floating point precision type to represent frequencies
   ///
   /// \param exec_space [in] Kokkos execution space
   /// \param n [in] Window length
   /// \param d [in] Sample spacing (default, 1)
   ///
   /// \return Sampling frequency
   template <typename ExecutionSpace, typename RealType>
   auto fftfreq(const ExecutionSpace&, const std::size_t n,
                const RealType d = 1.0) {
   

   A class definition should be documented in the following manner (rendered version is found here). Class methods can be documented in the same way as functions.

   /// \brief A class that manages a FFT plan of backend FFT library.
   ///
   /// This class is used to manage the FFT plan of backend FFT library.
   /// Depending on the input and output Views and axes, appropriate FFT plans are
   /// created. If there are inconsistency in input and output views, the
   /// compilation would fail.
   ///
   /// \tparam ExecutionSpace: The type of Kokkos execution space
   /// \tparam InViewType: Input View type for the fft
   /// \tparam OutViewType: Output View type for the fft
   /// \tparam DIM: The dimensionality of the fft
   template <typename ExecutionSpace, typename InViewType, typename OutViewType,
             std::size_t DIM = 1>
   class Plan {
   

2. Make a ReStructuredText file: To generate documentations only for APIs, we place functions and/or classes in the ReStructuredText (rst) file. Here are the examples for a function and a class (rendered versions are found at here and here). For overloaded functions, you need to also describe the arguments of the function.

   .. doxygenfunction:: KokkosFFT::fftfreq
   

   .. doxygenclass:: KokkosFFT::Plan
      :members:
   

3. Generate the Documentation Locally: After making changes to the source code or its docstrings, build the documentation locally to verify that the API reference updates correctly. You can compile and build the documentation by

   cmake -B build_doc -DKokkosFFT_ENABLE_DOCS=ON
   cmake --build build_doc -j 8
   

   You will find your documentation at build_doc/docs/sphinx/index.html.