AST-933 Add sphinx documentation

.gitlab-ci.common.yml

@@ -167,3 +167,17 @@ test-2204:
       coverage_report:
         coverage_format: cobertura
         path: build/reports/code-coverage.xml
+
+build-doc-2204:
+  extends: .needs-2204
+  stage: build
+  image: $BASE_IMAGE_2204
+  script:
+    - RADLER_PATH=$PWD
+    - mkdir build && cd build
+    - cmake -DBUILD_PYTHON_BINDINGS=ON -DBUILD_DOCUMENTATION=ON $RADLER_PATH -G Ninja
+    - ninja
+    - ninja doc
+  artifacts:
+    paths:
+    - build/doc/html

CMakeLists.txt

@@ -8,6 +8,7 @@ include(ExternalProject)
 option(COMPILE_AS_EXTERNAL_PROJECT OFF)
 option(PORTABLE "Generate portable code" OFF)
 option(BUILD_PYTHON_BINDINGS "Build python bindings" OFF)
+option(BUILD_DOCUMENTATION "Build documentation" OFF)
 
 set(RADLER_VERSION 0.0.0)
 project(radler VERSION ${RADLER_VERSION})
@@ -22,6 +23,10 @@ endif()
 if(POLICY CMP0076)
   cmake_policy(SET CMP0076 NEW)
 endif()
+if(POLICY CMP0115)
+  # Prevent warning about extensions, specifically about Doxyfile
+  cmake_policy(SET CMP0115 NEW)
+endif()
 
 set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED YES)
@@ -210,3 +215,7 @@ if(NOT ${COMPILE_AS_EXTERNAL_PROJECT} AND ${BUILD_TESTING})
   # demo targets are excluded from a default build
   add_subdirectory(cpp/demo)
 endif()
+
+if(BUILD_DOCUMENTATION)
+  add_subdirectory(doc)
+endif()

cmake/FindSphinx.cmake

+# CMake find_package() Module for Sphinx documentation generator
+# http://sphinx-doc.org/
+#
+# Example usage:
+#
+# find_package(Sphinx)
+#
+# If successful the following variables will be defined SPHINX_FOUND
+# SPHINX_EXECUTABLE
+
+find_program(
+  SPHINX_EXECUTABLE
+  NAMES sphinx-build sphinx-build2
+  DOC "Path to sphinx-build executable")
+
+# Handle REQUIRED and QUIET arguments this will also set SPHINX_FOUND to true if
+# SPHINX_EXECUTABLE exists
+include(FindPackageHandleStandardArgs)
+find_package_handle_standard_args(
+  Sphinx "Failed to locate sphinx-build executable" SPHINX_EXECUTABLE)
+
+# Provide options for controlling different types of output
+option(SPHINX_OUTPUT_HTML "Output standalone HTML files" ON)
+option(SPHINX_OUTPUT_MAN "Output man pages" ON)
+
+option(SPHINX_WARNINGS_AS_ERRORS
+       "When building documentation treat warnings as errors" ON)

cpp/radler.h

@@ -32,8 +32,8 @@ class Radler {
   /**
    * @brief Constructor for single channel, single polarization deconvolution.
    * @param[in] psf_image PSF image.
-   * @param[in/out] residual_image Residual image.
-   * @param[in/out] model_image Model image.
+   * @param[in,out] residual_image Residual image.
+   * @param[in,out] model_image Model image.
    *
    * Please bear in mind to keep the data buffer in the input images alive in
    * the caller, since Radler internally points to this data buffer during calls

cpp/settings.h

@@ -167,12 +167,12 @@ struct Settings {
    * @brief Sigma value for automatically creating and applying mask images.
    *
    * If set, Radler performs these steps:
-   * # Radler starts cleaning towards a threshold of the given sigma value.
-   * # Once the sigma level is reached, Radler generates a mask using the
-   * positions and (when using multi-scale cleaning) scale of each component.
-   * # Cleaning then continues until the final threshold value, as set using the
-   * @ref threshold or @ref auto_threshold_sigma values. During this final
-   * deconvolution stage, the generated mask constrains the cleaning.
+   * - Radler starts cleaning towards a threshold of the given sigma value.
+   * - Once the sigma level is reached, Radler generates a mask using the
+   *   positions and (when using multi-scale cleaning) scale of each component.
+   * - Cleaning then continues until the final threshold value, as set using the
+   *   @ref threshold or @ref auto_threshold_sigma values. During this final
+   *   deconvolution stage, the generated mask constrains the cleaning.
    *
    * If unset, automatic masking is not used.
    */

doc/CMakeLists.txt

+find_package(Doxygen REQUIRED)
+find_package(Sphinx REQUIRED)
+
+set(RADLER_SO_PATH ${CMAKE_BINARY_DIR}/python)
+
+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_GENERATED ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+
+# Replace variables inside @@ with the current values
+configure_file(${DOXYFILE_IN} ${DOXYFILE_GENERATED} @ONLY)
+
+# This will be the main output of our command
+set(DOXYGEN_INDEX_FILE "${DOXYGEN_OUTPUT_DIR}/xml/index.xml")
+
+add_custom_command(
+  OUTPUT ${DOXYGEN_INDEX_FILE}
+  COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_GENERATED}
+  WORKING_DIRECTORY ${DOXYGEN_OUTPUT_DIR}
+  MAIN_DEPENDENCY Doxyfile
+  COMMENT "Generating doxygen documentation")
+
+set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
+set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR}/html)
+
+add_custom_target(
+  doc
+  ${CMAKE_COMMAND}
+  -E
+  env
+  RADLER_SO_PATH=${RADLER_SO_PATH}
+  ${SPHINX_EXECUTABLE}
+  -b
+  html
+  ${SPHINX_SOURCE}
+  ${SPHINX_BUILD}
+  # Tell Breathe where to find the Doxygen output
+  -Dbreathe_projects.Radler=${DOXYGEN_OUTPUT_DIR}/xml
+  WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+  COMMENT "Generating documentation with Sphinx"
+  DEPENDS ${DOXYGEN_INDEX_FILE} pyradler)

doc/Doxyfile.in

+# Doxyfile 1.8.13
+
+PROJECT_NAME           = "Radler"
+PROJECT_NUMBER         = "@RADLER_VERSION@"
+OUTPUT_DIRECTORY       = "@DOXYGEN_OUTPUT_DIR@"
+FULL_PATH_NAMES        = NO
+AUTOLINK_SUPPORT       = NO
+BUILTIN_STL_SUPPORT    = YES
+
+EXTRACT_ALL            = YES
+HIDE_SCOPE_NAMES       = YES
+
+INPUT                  = @CMAKE_SOURCE_DIR@/cpp
+RECURSIVE              = YES
+EXCLUDE_PATTERNS       = */external/* \
+
+ALPHABETICAL_INDEX     = NO
+
+GENERATE_HTML          = NO
+
+GENERATE_LATEX         = NO
+
+GENERATE_RTF           = NO
+
+GENERATE_MAN           = NO
+
+GENERATE_XML           = YES
+
+GENERATE_DOCBOOK       = NO
+
+GENERATE_PERLMOD       = NO
+
+CLASS_DIAGRAMS         = NO

doc/build-instructions.rst

+.. _buildinstructions:
+
+Build instructions
+==================
+
+Radler can be installed as a stand-alone package, but is also installed as a part of `WSClean <https://wsclean.readthedocs.io>`_. 
+If you only want to install WSClean, it is not necessary to build Radler yourself.
+
+Dependencies
+~~~~~~~~~~~~
+Radler needs a number of dependencies in order to successfully compile. On a clean (ubuntu 22.04) system,
+the dependencies can be installed with (see also the ``docker`` directory):
+
+General packages:
+
+::
+
+    apt-get -y install wget git make cmake g++ doxygen \
+    libboost-all-dev libhdf5-dev libfftw3-dev \
+    libblas-dev liblapack-dev libgsl-dev libxml2-dev \
+    libgtkmm-3.0-dev libpython3-dev python3-distutils
+
+Astronomy-specific packages:
+
+::
+
+    apt-get -y install casacore-dev libcfitsio-dev
+
+In order to be able to build the documentation with ``make doc``, ``sphinx`` and some other documentation tools need to be installed:
+
+::
+
+    pip3 install sphinx doxygen sphinx_rtd_theme breathe myst-parser
+
+
+
+
+Quick installation guide
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    git clone --recursive https://git.astron.nl/RD/Radler.git
+    cd Radler
+    mkdir build && cd build
+    cmake -DCMAKE_INSTALL_PREFIX=<radler_install_path> ..
+    make install
+
+
+Installation options
+~~~~~~~~~~~~~~~~~~~~
+
+(Use :code:`ccmake` or :code:`cmake -i` to configure all options.)
+
+* :code:`BUILD_WITH_PYTHON`: build Python module 'radler' to use Radler from Python
+* :code:`BUILD_TESTING`: compile tests
+
+All other build options serve development purposes only, and can/should be left at the default values by a regular user.
+
+All libraries are installed in :code:`<installpath>/lib`. The header files in
+:code:`<installpath>/include`. The Python module in
+:code:`<installpath>/lib/python{VERSION_MAJOR}.{VERSION_MINOR}/site-packages`. Make sure that your
+:code:`LD_LIBRARY_PATH` and :code:`PYTHONPATH` are set as appropiate.

doc/conf.py

+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# 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
+
+# Make sure that it refers to the shared object file from current build
+sys.path.insert(0, os.environ["RADLER_SO_PATH"])
+
+# -- Project information -----------------------------------------------------
+
+project = "Radler"
+copyright = "2022, ASTRON (Netherlands Institute for Radio Astronomy)"
+author = "André Offringa"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx_rtd_theme",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "breathe",
+    "myst_parser",
+]
+
+# Disable typehints in signatures - doens't seem to take any effect
+autodoc_typehints = "none"
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+html_static_path = ["_static"]
+
+# Breathe Configuration
+breathe_default_project = "Radler"

doc/index.rst

+.. include:: ../README.md
+   :parser: myst_parser.sphinx_
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: Getting Started
+
+   build-instructions
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :titlesonly:
+   :caption: Interfaces
+
+   tree/interfaces-overview
+   tree/cpp-interface
+   tree/python-interface
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :caption: Indices and Tables
+
+   indices-and-tables

doc/indices-and-tables.rst

+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`
\ No newline at end of file

doc/tree/cpp-interface.rst

+C++ interface
+=============
+
+Below the most important parts of the Radler C++ API are documented.
+
+.. toctree::
+   :maxdepth: 1
+
+   cpp/algorithms
+   cpp/settings

doc/tree/cpp/algorithms.rst

+.. _radler::algorithms:
+
+Algorithms
+====================
+
+.. doxygenenum:: AlgorithmType

doc/tree/cpp/settings.rst

+.. _radler::settings:
+
+Settings
+====================
+
+.. doxygenstruct:: radler::Settings
+   :members:

doc/tree/interfaces-overview.rst

+Interface overview
+======================
+
+Radler is primarily written in :code:`C++`. If Radler was compiled with :code:`BUILD_PYTHON_BINDINGS=ON`
+Python bindings are generated to interface the Radler API from within Python. See below for the documentation of the
+:code:`C++` and the :code:`Python` interface.

doc/tree/python-interface.rst

+Python interface
+================
+
+Radler provides an interface via the :code:`radler` module. In order to build
+this module, make sure the cmake configuration option :code:`BUILD_PYTHON_BINDINGS` is turned :code:`ON`.
+
+After successfully compiling and installing the python bindings, you should update your :code:`LD_LIBRARY_PATH`
+and your :code:`PYTHONPATH` as follows:
+
+::
+
+    export LD_LIBRARY_PATH=<installpath>/lib/:$LD_LIBRARY_PATH
+    export PYTHONPATH=<installpath>/lib/python<VERSION_MAJOR>.<VERSION_MINOR>/site-packages:$PYTHONPATH
+
+where :code:`VERSION_MAJOR` and :code:`VERSION_MINOR` depend upon the specific version of python on your system.
+The :code:`radler` module can now be imported in python with:
+
+::
+
+    import radler
+
+.. toctree::
+   :maxdepth: 1
+
+   python/settings

doc/tree/python/settings.rst

+Settings
+========
+
+Classes
+~~~~~~~
+.. autoclass:: radler.Settings
+   :members:
+   :undoc-members:

docker/ubuntu_20_04_base

@@ -22,6 +22,7 @@ RUN export DEBIAN_FRONTEND="noninteractive" && \
         libhdf5-dev \
         libpython3-dev \
         make \
+        ninja-build \
         python3-pip \
         wcslib-dev \
         wget \
@@ -34,8 +35,12 @@ RUN export DEBIAN_FRONTEND="noninteractive" && \
     && \
     ln -sf clang-tidy-12 /usr/bin/clang-tidy
 RUN python3 -m pip install \
+        breathe \
         cmake-format \
+        myst-parser \
         numpy \
         pytest \
         pytest-lazy-fixture \
-    ;
\ No newline at end of file
+        sphinx \
+        sphinx_rtd_theme \
+    ;

docker/ubuntu_22_04_base

@@ -22,6 +22,7 @@ RUN export DEBIAN_FRONTEND="noninteractive" && \
         libhdf5-dev \
         libpython3-dev \
         make \
+        ninja-build \
         python3-pip \
         wcslib-dev \
         wget \
@@ -34,8 +35,12 @@ RUN export DEBIAN_FRONTEND="noninteractive" && \
     && \
     ln -sf clang-tidy-12 /usr/bin/clang-tidy
 RUN python3 -m pip install \
+        breathe \
         cmake-format \
+        myst-parser \
         numpy \
         pytest \
         pytest-lazy-fixture \
-    ;
\ No newline at end of file
+        sphinx \
+        sphinx_rtd_theme \
+    ;

python/pysettings.cc

@@ -130,6 +130,7 @@ void init_settings(py::module& m) {
         Sigma value for automatically creating and applying mask images.
 
         If set, Radler performs these steps:
+
         - Radler starts cleaning towards a threshold of the given sigma value.
         - Once the sigma level is reached, Radler generates a mask using the
           positions and (when using multi-scale cleaning) scale of each component.