added sphinx to cmake

CHANGELOG

@@ -52,6 +52,8 @@ V 2.3.0beta (7/24/24)
   Added support for Windows (llvm, msvc), Linux (llvm, gcc) and MacOS (llvm, gcc).
 * cmake support for both ducc0 and fftw
 * cmake adding nvcc and msvc optimization flags
+* cmake supports sphinx
+* updated install docs
 
 V 2.2.0 (12/12/23)
 

CMakeLists.txt

@@ -105,10 +105,6 @@ if(FINUFFT_ARCH_FLAGS STREQUAL "native")
   endif()
 endif()
 
-if(CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
-  include(CTest)
-endif()
-
 # Set default build type to Release
 if(NOT CMAKE_BUILD_TYPE)
   set(CMAKE_BUILD_TYPE
@@ -140,20 +136,25 @@ function(enable_asan target)
   endif()
 endfunction()
 
+set(CPM_DOWNLOAD_VERSION 0.40.0)
+include(cmake/setupCPM.cmake)
+
+if(CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
+  include(CTest)
+  include(cmake/setupSphinx.cmake)
+endif()
+
 if(FINUFFT_USE_CPU)
   # make apple with gnu use old linker, new linker breaks, see issue #360
   if((APPLE) AND (CMAKE_CXX_COMPILER_ID STREQUAL "GNU"))
     add_link_options("-ld_classic")
   endif()
-
-  set(CPM_DOWNLOAD_VERSION 0.40.0)
   set(FFTW_VERSION 3.3.10)
   set(XTL_VERSION 0.7.7)
   set(XSIMD_VERSION 13.0.0)
   # using latest ducc0 version for now as it fixes MacOS GCC build
   set(DUCC0_VERSION b0beb85e03982344a31ebb119758d7aa3ef5d362)
   set(FINUFFT_FFTW_LIBRARIES)
-  include(cmake/setupCPM.cmake)
   include(cmake/setupXSIMD.cmake)
   if(FINUFFT_USE_DUCC0)
     include(cmake/setupDUCC.cmake)

cmake/setupSphinx.cmake

@@ -0,0 +1,21 @@
+cpmaddpackage(
+  NAME
+  sphinx_cmake
+  GIT_REPOSITORY
+  https://github.com/k0ekk0ek/cmake-sphinx.git
+  GIT_TAG
+  e13c40a
+  DOWNLOAD_ONLY
+  YES)
+
+list(APPEND CMAKE_MODULE_PATH ${sphinx_cmake_SOURCE_DIR}/cmake/Modules)
+
+# requires pip install sphinx texext
+find_package(Sphinx)
+if(SPHINX_FOUND)
+  message(STATUS "Sphinx found")
+  sphinx_add_docs(finufft_sphinx BUILDER html SOURCE_DIRECTORY
+                  ${FINUFFT_SOURCE_DIR}/docs)
+else()
+  message(STATUS "Sphinx not found docs will not be generated")
+endif()

docs/devnotes.rst

@@ -4,7 +4,8 @@ Developer notes
 ===============
 
 * Developers needing to update/regenerate documentation in general, including our readthedocs website, see ``docs/README``. Developers changing MATLAB/octave interfaces or docs, also see ``matlab/README``. Please also see ``contributing.md`` for code style and git hook guidelines.
-
+* cmake supports sphinx generation one can do by ``cmake --build . --target finufft_sphinx``. This will crete a folder called finufft_sphinx in your build directory, opening ``index.html`` will preview the updated documentation.
+* cmake sphinx requires shpinx and texext to be installed in python
 * To update the version number, this needs to be done by hand in the following places:
 
   - ``CMakeLists.txt`` for cmake
@@ -27,11 +28,11 @@ Developer notes
 * The kernel function in spreadinterp is evaluated via piecewise-polynomial approximation (Horner's rule). The code for this is auto-generated in MATLAB, for all upsampling factors. There are two versions supported:
 
   - 2018--2024 vintage: no explicit SIMD vectorization, C code is generated code for the Horner evaluation loop, by running from MATLAB `gen_all_horner_C_code.m`
-    
+
   - post-2024 vintage: explicit SIMD and many other acceleration tricks, and the generated code is a static C++ array of coefficients, and their sizes (`nc` or number of coefficients) for each width `w`. Run from MATLAB `gen_ker_horner_loop_cpp_code.m`
 
   See `devel/README` for more details. The ES kernel coefficient and poly approx degree for both of the above are defined in a single location, `devel/get_degree_and_beta.m`, which must match the C++ `setup_spreader()` function.
-  
+
 * Continuous Integration (CI). See files for this in ``.github/workflows/``. It currently tests the default ``makefile`` settings in linux, and three other ``make.inc.*`` files covering OSX and Windows (MinGW). CI does not test build the variant OMP=OFF. The dev should test these locally. Likewise, the Julia wrapper is separate and thus not tested in CI. We have added ``JenkinsFile`` for the GPU CI via python wrappers.
 
 * **Installing MWrap**. This is needed only for experts to rebuild the matlab/octave interfaces.
@@ -43,7 +44,7 @@ Developer notes
   Make sure to override the location of MWrap by adding a line such as::
 
     MWRAP = your-path-to-mwrap-executable
-  
+
   to your ``make.inc``, and then you can use the ``make mex`` task.
 
 * The cufinufft Python wheels are generated using Docker based on the manylinux2014 image. For instructions, see ``tools/cufinufft/distribution_helper.sh``. These are binary wheels that are built using CUDA 11 (or optionally CUDA 12, but these are not distributed on PyPI) and bundled with the necessary libraries.

docs/install.rst

@@ -12,19 +12,19 @@ a precompiled binary for your platform under Assets for various
 `releases <https://github.com/flatironinstitute/finufft/releases>`_.
 Please post an `Issue <https://github.com/flatironinstitute/finufft/issues>`_
 to document your installation problem.
+When using CMake, finufft requires no external dependencies except (c/c++ compilers supporting OpenMP).
+However GNU ``makefile`` assumes that FFTW (single/double) are installed.
 
-.. warning::
-
-    finufft builds with no issues on Linux using any compiler, in our experience GCC-13 gives best performance.
-    On MacOS both GCC and clang are fine.
-    On Windows MSVC works fine. The llvm toolchain included in Visual Studio does not seem to have OpenMP.
-    The official LLVM distribution builds finufft but debug builds using sanitizers break.
+.. note::
+    finufft builds with no issues on Linux and MacOS using any compiler, in our experience GCC-13 gives best performance.
+    On Windows MSVC works fine. The llvm toolchain included in Visual Studio does not seem to have OpenMP, it is possible to build single-threaded FINUFFT.
+    The official windows LLVM distribution builds finufft with no issues but debug builds using sanitizers break.
 
 .. note::
 
     On windows finufft built with MSVC requires ``VCOMP140D.DLL`` which is part of the `Microsoft Visual C++ Redistributable <https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170>`_.
+    It is likely to be already installed in your system.
     If the library is built with LLVM it requires ``libomp140.x86.64.dll``, more information `here <https://devblogs.microsoft.com/cppblog/improved-openmp-support-for-cpp-in-visual-studio/>`_.
-
     Python-only users can simply install via ``pip install finufft`` which downloads a generic binary from PyPI. Only if you prefer a custom compilation, see :ref:`below<install-python>`.
 
 CMake CPM Based Installation
@@ -39,10 +39,14 @@ Then add the following to your ``CMakeLists.txt``:
 
 .. code-block:: cmake
 
+  # short version
+  CPMAddPackage("gh:flatironinstitute/[email protected]")
+
+  # alternative in case custom options are needed
   CPMAddPackage(
     NAME             Finufft
     GIT_REPOSITORY   https://github.com/flatironinstitute/finufft.git
-    GIT_TAG          master
+    GIT_TAG          2.3
     GIT_SHALLOW      Yes
     GIT_PROGRESS     Yes
     EXCLUDE_FROM_ALL Yes
@@ -61,6 +65,7 @@ which is provided directly by cmake.
 To do so add the following to your ``CMakeLists.txt``:
 
 .. code-block:: cmake
+
     include(FetchContent)
 
     # Define the finufft library
@@ -76,6 +81,8 @@ To do so add the following to your ``CMakeLists.txt``:
     # Optionally, link the finufft library to your target
     target_link_libraries(your_executable [PUBLIC|PRIVATE|INTERFACE] finufft)
 
+Then cmake will automatically download the library and link it to your executable.
+
 CMake Based Installation
 ------------------------
 
@@ -96,7 +103,7 @@ The basic quick download, building, and test is then:
 
    If you don't supply `--install-prefix`, it will default to ``/usr/local`` on most systems. If you don't have root access, you must supply a prefix you can write to such as ``$HOME/local``.
 
-In ``build``, this creates ``libfinufft_static.a`` and ``libfinufft.so``, and runs a test that should take a
+In ``build``, this creates ``libfinufft.a`` or ``libfinufft.so``, and runs a test that should take a
 few seconds and report ``100% tests passed, 0 tests failed out of 17``.  To use the library, link against
 either the static or dynamic library in ``build`` or your installed version
 (i.e. ``/path/to/install/lib64/libfinufft.so`` or ``/path/to/install/lib/libfinufft.so``). If you install
@@ -164,7 +171,7 @@ If there is an error in testing on what you consider a standard set-up,
 please file a detailed bug report as a New Issue at https://github.com/flatironinstitute/finufft/issues
 
 
-Quick linux install instructions
+Quick linux GNU MAKE install instructions
 --------------------------------
 
 Make sure you have packages ``fftw3`` and ``fftw3-dev`` (or their
@@ -240,7 +247,7 @@ This compiles the main libraries then runs double- and single-precision tests, e
 .. note::
 
    GCC versions on linux: long-term linux distros ship old GCC versions
-   that may not be C++14 compatible. We recommend that you
+   that may not be C++17 compatible. We recommend that you
    compile with a recent GCC, at least GCC 7.3 (which we used
    for benchmarks in 2018 in our SISC paper), or GCC 9+. We do not recommend
    GCC versions prior to 7. We also **do not recommend GCC8** since
@@ -445,7 +452,7 @@ section of ``mexopts.sh``.
 
 
 
-3) Windows: tips for compiling
+3) Windows GNU MAKE: tips for compiling
 -------------------------------
 
 We have users who have adjusted the makefile to work - at least to some extent - on Windows 10. If you are only interested in calling from Octave (which already comes with MinGW-w64 and FFTW), then we have been told this can be done very simply: from within Octave, go to the ``finufft`` directory and do ``system('make octave')``. You may have to tweak ``OCTAVE`` in your ``make.inc`` in a similar fashion to below.