From d86ecfed71133b379f281d48c54a08e80e4a9eb8 Mon Sep 17 00:00:00 2001
From: Maik Nijhuis <maik.nijhuis@triopsys.nl>
Date: Wed, 15 Jun 2022 07:51:02 +0000
Subject: [PATCH] AST-919 Publish to ReadTheDocs

---
 .readthedocs.yaml         | 31 ++++++++++++++++++++
 README.md                 | 14 ++++-----
 doc/CMakeLists.txt        | 57 +++++++++++++++--------------------
 doc/build-instructions.md | 31 +++++++++-----------
 doc/conf.py               | 15 ++++------
 doc/requirements.txt      |  7 +++++
 idg-lib/README.md         | 62 +++++++++++++++++++--------------------
 7 files changed, 118 insertions(+), 99 deletions(-)
 create mode 100644 .readthedocs.yaml
 create mode 100644 doc/requirements.txt

diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644
index 000000000..8855c1ad3
--- /dev/null
+++ b/.readthedocs.yaml
@@ -0,0 +1,31 @@
+# Copyright (C) 2022 ASTRON (Netherlands Institute for Radio Astronomy)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.9"
+  apt_packages:
+    - cmake
+    - doxygen
+    - libfftw3-dev # IDG always requires FFTW3.
+    - liblapacke-dev # IDG always requires LAPACK.
+    - ninja-build
+  jobs:
+    pre_build:
+      # Build doxygen documentation
+      - mkdir build
+      - cmake -S . -B build -G Ninja
+      - cd build && ninja doxygen
+
+sphinx:
+  configuration: doc/conf.py
+
+python:
+  install:
+    - requirements: doc/requirements.txt
diff --git a/README.md b/README.md
index 4ee3e3478..847dea154 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,15 @@
 # Image Domain Gridding (IDG)
 
-The documentation of IDG can be found [here](https://www.astron.nl/citt/IDG/).
+The documentation of IDG can be found [here](https://idg.readthedocs.io).
 
-This repository will contain the three subprojects of Image Domain Gridding:
- * [idg-lib](https://gitlab.com/astron-idg/idg-lib): The core library
- * [idg-bin](https://gitlab.com/astron-idg/idg-bin): Examples in C++ and Python
- * [idg-api](https://gitlab.com/astron-idg/idg-api): An API which is used in WSClean
-
-Each repository can also be installed separately if desired.
+This repository contains the three subprojects of Image Domain Gridding:
+ * [idg-lib](https://git.astron.nl/RD/idg/-/tree/master/idg-lib): The core library
+ * [idg-bin](https://git.astron.nl/RD/idg/-/tree/master/idg-bin): Examples in C++ and Python
+ * [idg-api](https://git.astron.nl/RD/idg/-/tree/master/idg-api): An API which is used in WSClean
 
 # Installation
 ```
-git clone https://gitlab.com/astron-idg/idg.git
+git clone https://git.astron.nl/RD/idg.git
 cd idg && mkdir build && cd build
 cmake -DCMAKE_INSTALL_PREFIX=/usr/local/idg/ ..
 ccmake . # For interactively setting parameters, like BUILD_LIB_CUDA
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index 28212ab5b..b033bbbe2 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -1,49 +1,41 @@
-find_package(Sphinx)
+# Copyright (C) 2022 ASTRON (Netherlands Institute for Radio Astronomy)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 find_package(Doxygen)
 
-if(NOT (SPHINX_FOUND AND DOXYGEN_FOUND))
-  set(missing_packages "Doxygen and Sphinx")
-  if(SPHINX_FOUND)
-    set(missing_packages "Doxygen")
-  endif()
-  if(DOXYGEN_FOUND)
-    set(missing_packages "Sphinx")
-  endif()
+if(NOT DOXYGEN_FOUND)
   add_custom_target(
-    doc
+    doxygen
     COMMAND
       echo -e
-      "\\nTo make the documentation please install ${missing_packages}, rerun cmake and then run make doc\\n"
+      "\\nDoxygen is not found. Please install Doxygen, rerun cmake and try again.\\n"
     COMMAND exit 1
     VERBATIM)
 else()
-
-  find_package(Doxygen REQUIRED)
-
-  # Find all the public headers
-  # get_target_property(CAT_CUTIFIER_PUBLIC_HEADER_DIR CatCutifier INTERFACE_INCLUDE_DIRECTORIES)
-  # file(GLOB_RECURSE CAT_CUTIFIER_PUBLIC_HEADERS ${CAT_CUTIFIER_PUBLIC_HEADER_DIR}/*.h)
-
   set(DOXYGEN_OUTPUT_DIR "${CMAKE_CURRENT_BINARY_DIR}/doxygen")
   file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})
 
-  set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
-  set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
-
   #Replace variables inside @@ with the current values
-  configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
-
-  #This will be the main output of our command
-  set(DOXYGEN_INDEX_FILE "${DOXYGEN_OUTPUT_DIR}/xml/index.xml")
+  configure_file(Doxyfile.in Doxyfile @ONLY)
 
-  add_custom_command(
-    OUTPUT ${DOXYGEN_INDEX_FILE}
-    # DEPENDS ${CAT_CUTIFIER_PUBLIC_HEADERS}
-    COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
+  add_custom_target(
+    doxygen
+    COMMAND ${DOXYGEN_EXECUTABLE} ../Doxyfile
     WORKING_DIRECTORY ${DOXYGEN_OUTPUT_DIR}
-    MAIN_DEPENDENCY Doxyfile
-    COMMENT "Generating doxygen docs")
+    COMMENT "Generating documentation with Doxygen")
+endif()
 
+find_package(Sphinx)
+
+if(NOT SPHINX_FOUND)
+  add_custom_target(
+    doc
+    COMMAND
+      echo -e
+      "\\nSphinx is not found. Please install Sphinx, rerun cmake and try again.\\n"
+    COMMAND exit 1
+    VERBATIM)
+else()
   set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
   set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/html)
 
@@ -55,6 +47,5 @@ else()
       -Dbreathe_projects.IDG=${DOXYGEN_OUTPUT_DIR}/xml
     WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
     COMMENT "Generating documentation with Sphinx"
-    DEPENDS ${DOXYGEN_INDEX_FILE})
-
+    DEPENDS doxygen)
 endif()
diff --git a/doc/build-instructions.md b/doc/build-instructions.md
index 87a61fa40..ab5a22b28 100644
--- a/doc/build-instructions.md
+++ b/doc/build-instructions.md
@@ -1,30 +1,27 @@
 # Build instructions
 
-## Quick installation guide:      
+## Quick installation guide:
 ```
-git clone --recursive -j4 https://gitlab.com/astron-idg/idg.git      
-cd idg     
-mkdir build; cd build           
-cmake -DCMAKE_INSTALL_PREFIX=<idg_install_path> ..       
+git clone --recursive -j4 https://git.astron.nl/RD/idg.git
+cd idg
+mkdir build; cd build
+cmake -DCMAKE_INSTALL_PREFIX=<idg_install_path> ..
 make install
 ```
 
-## Installation options:      
-(Best: use `ccmake` or `cmake -i` to configure all options.)       
+## Installation options:
+(Best: use `ccmake` or `cmake -i` to configure all options.)
 ```
-* BUILD_STATIC_LIBS: build static libraries, instead of shared ones       
-* BUILD_LIB_CPU: build library 'libidg-cpu' for usage on CPU's      
-* BUILD_LIB_CUDA: build library 'libidg-cuda' for usage on Nvidia GPU's      
-* BUILD_LIB_OPENCL: build library 'libidg-opencl' for usage of OpenCL     
-* BUILD_WITH_PYTHON: build Python module 'idg' to use IDG from Python       
+* BUILD_STATIC_LIBS: build static libraries, instead of shared ones
+* BUILD_LIB_CPU: build library 'libidg-cpu' for usage on CPU's
+* BUILD_LIB_CUDA: build library 'libidg-cuda' for usage on Nvidia GPU's
+* BUILD_LIB_OPENCL: build library 'libidg-opencl' for usage of OpenCL
+* BUILD_WITH_PYTHON: build Python module 'idg' to use IDG from Python
 ```
 All other build options are for development purposes only, and should be
-left at the default values by a regular user.      
+left at the default values by a regular user.
 
 All libraries are installed in `'<installpath>/lib'`. The header files in
 `'<installpath>/include'`. The Python module in
 `'<installpath>/lib/python3.8/site-packages'`. Make sure that your
-`LD_LIBRARY_PATH` and `PYTHONPATH` are set as appropiate.      
-
-
-
+`LD_LIBRARY_PATH` and `PYTHONPATH` are set as appropiate.
diff --git a/doc/conf.py b/doc/conf.py
index 850dc95bf..362169829 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -4,16 +4,7 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-import sphinx_rtd_theme
+import os
 
 # -- Project information -----------------------------------------------------
 
@@ -52,4 +43,8 @@ html_css_files = ['extra.css']
 html_static_path = ['_static']
 
 # Breathe Configuration
+# When using CMake, the 'doc' target already sets breathe_projects.
+if 'READTHEDOCS' in os.environ:
+    breathe_projects = { "IDG": "../build/doc/doxygen/xml" }
+
 breathe_default_project = "IDG"
diff --git a/doc/requirements.txt b/doc/requirements.txt
new file mode 100644
index 000000000..658e11b41
--- /dev/null
+++ b/doc/requirements.txt
@@ -0,0 +1,7 @@
+# Copyright (C) 2022 ASTRON (Netherlands Institute for Radio Astronomy)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# Required python packages for building on ReadTheDocs.
+# See .readthedocs.yaml in the root of this repository.
+breathe
+myst-parser
diff --git a/idg-lib/README.md b/idg-lib/README.md
index 02fe2cdde..3f3991919 100644
--- a/idg-lib/README.md
+++ b/idg-lib/README.md
@@ -1,75 +1,75 @@
 # Introduction
 This library implements the image domain gridding method for gridding and degridding of visibilities from an aperture synthesis radio telescope.
 
-# Quick installation guide:      
+# Quick installation guide:
 ```
-git clone --recursive -j4 https://gitlab.com/astron-idg/idg.git      
-cd idg     
-mkdir build; cd build           
-cmake -DCMAKE_INSTALL_PREFIX=<idg_install_path> ..       
+git clone --recursive -j4 https://git.astron.nl/RD/idg.git
+cd idg
+mkdir build; cd build
+cmake -DCMAKE_INSTALL_PREFIX=<idg_install_path> ..
 make install
 ```
 
-## Installation options:      
-(Best: use `ccmake` or `cmake -i` to configure all options.)       
+## Installation options:
+(Best: use `ccmake` or `cmake -i` to configure all options.)
 ```
-* BUILD_STATIC_LIBS: build static libraries, instead of shared ones       
-* BUILD_LIB_CPU: build library 'libidg-cpu' for usage on CPU's      
-* BUILD_LIB_CUDA: build library 'libidg-cuda' for usage on Nvidia GPU's      
-* BUILD_LIB_OPENCL: build library 'libidg-opencl' for usage of OpenCL     
-* BUILD_WITH_PYTHON: build Python module 'idg' to use IDG from Python       
+* BUILD_STATIC_LIBS: build static libraries, instead of shared ones
+* BUILD_LIB_CPU: build library 'libidg-cpu' for usage on CPU's
+* BUILD_LIB_CUDA: build library 'libidg-cuda' for usage on Nvidia GPU's
+* BUILD_LIB_OPENCL: build library 'libidg-opencl' for usage of OpenCL
+* BUILD_WITH_PYTHON: build Python module 'idg' to use IDG from Python
 ```
 All other build options are for development purposes only, and should be
-left at the default values by a regular user.      
+left at the default values by a regular user.
 
 All libraries are installed in `'<installpath>/lib'`. The header files in
 `'<installpath>/include'`. The Python module in
 `'<installpath>/lib/python2.7/dist-packages'`. Make sure that your
-`LD_LIBRARY_PATH` and `PYTHONPATH` are set as appropiate.      
+`LD_LIBRARY_PATH` and `PYTHONPATH` are set as appropiate.
 
 
 # Using IDG in your own cmake project:
 
-## Finding IDG    
+## Finding IDG
 
-In your CMakeLists.txt file, use for instance:     
+In your CMakeLists.txt file, use for instance:
 
 `find_package(IDG NO_MODULE)`
 
-(See more on the find_package command in the cmake documentation.)      
+(See more on the find_package command in the cmake documentation.)
 
-When building your project, use `CMAKE_PREFIX_PATH` or `IDG_DIR`    
+When building your project, use `CMAKE_PREFIX_PATH` or `IDG_DIR`
 
 `cmake  -DCMAKE_PREFIX_PATH=<idg_install_path>  <project_src_path>`
-     
-or       
+
+or
 
 `cmake -DIDG_DIR=<idg_install_path> <project_src_path>`
 
 ## Predefined varibles from find_package
 
-*  `IDG_INCLUDE_DIR`: general include directories       
-*  `IDG_LIB`: IDG library to link against      
-*  `IDG_PYTHON_MODULE_PATH`: path to 'idg' python module    
+*  `IDG_INCLUDE_DIR`: general include directories
+*  `IDG_LIB`: IDG library to link against
+*  `IDG_PYTHON_MODULE_PATH`: path to 'idg' python module
 
 ## Linking against IDG
 
-For instance, for the CPU library, include the `idg-cpu.` in your source file. In cmake, set the include path and link to the libarary:     
+For instance, for the CPU library, include the `idg-cpu.` in your source file. In cmake, set the include path and link to the libarary:
 ```
-*include_directories (${IDG_INCLUDE_DIR})*    
-*target_link_libraries (a.out ${IDG_LIB})*      
+*include_directories (${IDG_INCLUDE_DIR})*
+*target_link_libraries (a.out ${IDG_LIB})*
 ```
 # Legal
 ASTRON has a patent pending on the Image Domain Gridding method implemented by
 this software.  This software is licensed under the GNU General Public License
-v3.0 (GPLv3.0).  That means that you are allowed to use, modify, distribute and 
+v3.0 (GPLv3.0).  That means that you are allowed to use, modify, distribute and
 sell this software under the conditions of GPLv3.0. For the exact terms of
-GPLv3.0, see the LICENSE file.  Making, using, distributing, or offering for 
+GPLv3.0, see the LICENSE file.  Making, using, distributing, or offering for
 sale of independent implementations of the Image Domain Gridding method, other
 than under GPLv3.0, might infringe upon patent claims by ASTRON. In that case
 you must obtain a license from ASTRON.
 
-ASTRON (Netherlands Institute for Radio Astronomy)  
-Attn. IPR Department  
-P.O.Box 2, 7990 AA Dwingeloo, The Netherlands  
+ASTRON (Netherlands Institute for Radio Astronomy)
+Attn. IPR Department
+P.O.Box 2, 7990 AA Dwingeloo, The Netherlands
 T +31 521 595100
-- 
GitLab