.. SPDX-FileCopyrightText: (C) The Kokkos-FFT development team, see COPYRIGHT.md file
..
.. SPDX-License-Identifier: MIT OR Apache-2.0 WITH LLVM-exception

Documentation
=============

We deploy the `Kokkos-FFT website <https://kokkosfft.readthedocs.io/en/latest/>`_ 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:

.. list-table:: ``Documentation structure``
   :widths: 50 50
   :header-rows: 1

   * - 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.

   .. code-block:: bash

      # 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 <https://www.doxygen.nl/manual/docblocks.html>`_.
To ensure accuracy and consistency:

#. **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 <https://kokkosfft.readthedocs.io/en/latest/api/helper/fftfreq.html>`__).

   .. code-block:: C++

     /// \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 <https://kokkosfft.readthedocs.io/en/latest/api/plan/plan.html>`__).
   Class methods can be documented in the same way as functions.

   .. code-block:: C++

     /// \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 {

#. **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 <https://kokkosfft.readthedocs.io/en/latest/api/helper/fftfreq.html>`__ and `here <https://kokkosfft.readthedocs.io/en/latest/api/plan/plan.html>`__).
   For overloaded functions, you need to also describe the arguments of the function.

   .. code-block:: rst
      
      .. doxygenfunction:: KokkosFFT::fftfreq

   .. code-block:: rst
      
      .. doxygenclass:: KokkosFFT::Plan
         :members:

#. **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

   .. code-block:: bash

      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``.