Improve readme and documentation, remove md parser

.gitlab-ci.common.yml

@@ -32,7 +32,7 @@ versioning:
     # Unshallowing ensures that 'git log' works
     - git fetch --unshallow
     - echo BASE_IMAGE_2004=${CI_REGISTRY_IMAGE}/base_2004:$(git log -n 1 --pretty=format:%H -- docker/ubuntu_20_04_base) > versions.env
-    - echo BASE_IMAGE_2204=${CI_REGISTRY_IMAGE}/base_2204:$(git log -n 1 --pretty=format:%H -- docker/ubuntu_22_04_base) >> versions.env
+    - echo BASE_IMAGE_2404=${CI_REGISTRY_IMAGE}/base_2404:$(git log -n 1 --pretty=format:%H -- docker/ubuntu_24_04_base) >> versions.env
     - cat versions.env
   artifacts:
     reports:
@@ -70,11 +70,11 @@ prepare-base-2004:
     DOCKER_IMAGE: $BASE_IMAGE_2004
     DOCKER_FILE: docker/ubuntu_20_04_base
 
-prepare-base-2204:
+prepare-base-2404:
   extends: .prepare
   variables:
-    DOCKER_IMAGE: $BASE_IMAGE_2204
-    DOCKER_FILE: docker/ubuntu_22_04_base
+    DOCKER_IMAGE: $BASE_IMAGE_2404
+    DOCKER_FILE: docker/ubuntu_24_04_base
 
 .needs-2004:
   needs:
@@ -83,21 +83,21 @@ prepare-base-2204:
       optional: true
   image: $BASE_IMAGE_2004
 
-.needs-2204:
+.needs-2404:
   needs:
     - job: versioning
-    - job: prepare-base-2204
+    - job: prepare-base-2404
       optional: true
-  image: $BASE_IMAGE_2204
+  image: $BASE_IMAGE_2404
 
 format:
-  extends: .needs-2204
+  extends: .needs-2404
   stage: linting
   script:
     - ./scripts/run-format.sh
 
 clang-tidy:
-  extends: .needs-2204
+  extends: .needs-2404
   stage: linting
   script:
     - mkdir -p build/reports
@@ -105,7 +105,7 @@ clang-tidy:
     # Generate compile_commands.json for clang-tidy.
     - cmake -DBUILD_TESTING=ON -DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=TRUE ..
     - cd ..
-    - clang-tidy-12 -p build/ `find cpp/ -name *.cc` | scripts/clang-tidy-to-junit.py . > build/reports/linting.xml
+    - clang-tidy -p build/ `find cpp/ -name *.cc` | scripts/clang-tidy-to-junit.py . > build/reports/linting.xml
   artifacts:
     when: always
     paths:
@@ -127,8 +127,8 @@ clang-tidy:
 build-2004:
   extends: [".needs-2004",".build"]
 
-build-2204:
-  extends: [".needs-2204",".build"]
+build-2404:
+  extends: [".needs-2404",".build"]
 
 .test:
   stage: test
@@ -152,10 +152,10 @@ test-2004:
   after_script:
     - gcovr -j`nproc` -e 'external/.*' -e '.*/CompilerIdCXX/.*' -e '.*/test/.*' build/
 
-test-2204:
+test-2404:
   extends: .test
-  needs: ["versioning","build-2204"]
-  image: $BASE_IMAGE_2204
+  needs: ["versioning","build-2404"]
+  image: $BASE_IMAGE_2404
   after_script:
     - mkdir -p build/reports
     - scripts/junit-merge.py build/reports/unit-tests.xml $(find build -name unittests_*.xml)
@@ -170,10 +170,10 @@ test-2204:
         coverage_format: cobertura
         path: build/reports/code-coverage.xml
 
-build-doc-2204:
-  extends: .needs-2204
+build-doc-2404:
+  extends: .needs-2404
   stage: build
-  image: $BASE_IMAGE_2204
+  image: $BASE_IMAGE_2404
   script:
     - mkdir build && cd build
     - cmake -DBUILD_PYTHON_BINDINGS=ON -DBUILD_DOCUMENTATION=ON .. -G Ninja
@@ -183,10 +183,10 @@ build-doc-2204:
     paths:
     - build/doc/html
 
-build-docstrings-2204:
-  extends: .needs-2204
+build-docstrings-2404:
+  extends: .needs-2404
   stage: build
-  image: $BASE_IMAGE_2204
+  image: $BASE_IMAGE_2404
   script:
     - mkdir build && cd build
     - cmake -DBUILD_DOCSTRINGS=ON -G Ninja ..

README.md

-# Radio Astronomical Deconvolution Library
+# Radler: Radio Astronomical Deconvolution Library
 
-Radler is a library providing functionality for deconvolving astronomical images. Radler evolved as a stand-alone library from the w-stacking clean (WSClean) imager, `https://gitlab.com/aroffringa/wsclean`_.
+Radler is a library providing functionality for deconvolving astronomical images. The library was split off from WSClean, `https://gitlab.com/aroffringa/wsclean`_ in order to enhance modularity and comparisons.
+
+## Documentation
+
+The Radler-specific documentation can be found here: `https://radler.readthedocs.io/`_, which includes how to interface with Radler from Python or C++. Information about the different methods and when to
+use which method (aimed at astronomers) can be found in the WSClean manual, `https://wsclean.readthedocs.io/`_. The WSClean documentation also contains references to scientific papers that describe the methods that are implemented
+in Radler.
 
 ## Testing
-Radler will be more extensively tested in the near-future. Tests for the core functionality - in particular the different `DeconvolutionAlgorithms` can be found in the `cpp/test` directory. Smaller scale unit tests can be found at namespace level (see, e.g., `cpp/math/test`)
+Tests for the core functionality - in particular the different deconvolution algorithms can be found in the `cpp/test` directory. Smaller scale unit tests can be found at namespace level (see, e.g., `cpp/math/test`).
 
 Some example scripts of how the C++ interface can be used, are found in the `cpp/demo` directory.
 

doc/build-instructions.rst

@@ -14,41 +14,35 @@ Radler can be installed from pypi:
 
     pip install radler
 
+This is the easiest way to install radler, but might not always contain the latest features. To be sure to have the latest features, build it from source.
 
 Building from source
 ~~~~~~~~~~~~~~~~~~~~
-Radler needs a number of dependencies in order to successfully compile. On a clean (ubuntu 22.04) system,
+Radler needs a number of dependencies in order to successfully compile. On a clean (Ubuntu 24.04) system,
 the dependencies can be installed with (see also the ``docker`` directory):
 
 General packages:
 
 ::
 
-    apt update && apt -y install git make cmake libpython3-dev g++ \
-    libboost-date-time-dev libhdf5-dev libfftw3-dev libgsl-dev python3-pip
+    apt install git make cmake libpython3-dev g++ casacore-dev \
+    libboost-date-time-dev libcfitsio-dev libfftw3-dev libgsl-dev \
+    libhdf5-dev
 
-Astronomy-specific packages:
+In order to be able to build the documentation with ``make doc`` and ``sphinx``, a few documentation tools need to be installed:
 
 ::
 
-    apt -y install casacore-dev libcfitsio-dev
+    apt -y install doxygen python3-pip
+    pip3 install sphinx sphinx_rtd_theme breathe
 
-In order to be able to build the documentation with ``make doc``, ``sphinx`` and some other documentation tools need to be installed:
 
-::
-
-    apt -y install doxygen
-    pip3 install sphinx sphinx_rtd_theme breathe myst-parser
-
-
-
-
-Quick installation guide
-~~~~~~~~~~~~~~~~~~~~~~~~
+Quick compilation guide
+~~~~~~~~~~~~~~~~~~~~~~~
 
 ::
 
-    git clone --recursive https://git.astron.nl/RD/Radler.git
+    git clone https://git.astron.nl/RD/Radler.git
     cd Radler
     mkdir build && cd build
     cmake -DBUILD_PYTHON_BINDINGS=On ..
@@ -64,9 +58,9 @@ Installation options
 * :code:`BUILD_PYTHON_BINDINGS`: 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 other build options serve development purposes only, and can 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.
+:code:`<installpath>/lib/python{VERSION_MAJOR}.{VERSION_MINOR}/site-packages`. Depending on your configuration, it might be necessary to set
+:code:`LD_LIBRARY_PATH` and :code:`PYTHONPATH` appropiately.

doc/conf.py

@@ -45,7 +45,6 @@ extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
     "breathe",
-    "myst_parser",
 ]
 
 # Disable typehints in signatures - doens't seem to take any effect

doc/index.rst

-.. include:: ../README.md
-   :parser: myst_parser.sphinx_
+Radler: Radio Astronomical Deconvolution Library
+================================================
+
+Radler is a library providing functionality for deconvolving astronomical images. The library was split off from WSClean, `https://gitlab.com/aroffringa/wsclean`_ in order to enhance modularity and comparisons.
+
+Documentation
+-------------
+
+This manual describes Radler-specific documentation, which includes how to interface with Radler from Python or C++.
+Information about the different methods and when to
+use which method (aimed at astronomers) can be found in `the WSClean manual <https://wsclean.readthedocs.io/>`_. The WSClean documentation also contains references to scientific papers that describe the methods that are implemented
+in Radler.
+
+For more information, contact André Offringa (offringa@gmail.com).
+
+License
+-------
+
+Radler is released under the LGPL version 3.
 
 .. toctree::
    :maxdepth: 2

doc/requirements.txt

@@ -3,6 +3,5 @@
 # Required python packages for building on ReadTheDocs.
 # See .readthedocs.yaml in the root of this repository.
 breathe
-myst-parser
 numpy
 sphinx_rtd_theme

doc/tree/cpp-interface.rst

 C++ interface
 =============
 
-Below the most important parts of the Radler C++ API are documented.
+The following sections describe the most important parts of the Radler C++ API.
 
 .. toctree::
    :maxdepth: 1

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.
+Radler is primarily written in ``C++``. If Radler was compiled with ``BUILD_PYTHON_BINDINGS=ON``
+Python bindings are generated to interface the Radler API from within Python. The next sections describe the
+``C++`` and the ``Python`` interface.

doc/tree/python-interface.rst

@@ -4,7 +4,7 @@ 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`
+After successfully compiling and installing the python bindings, you may have to update your :code:`LD_LIBRARY_PATH`
 and your :code:`PYTHONPATH` as follows:
 
 ::

docker/ubuntu_22_04_base → docker/ubuntu_24_04_base

 # SPDX-License-Identifier: LGPL-3.0-only
 
 # base
-FROM ubuntu:22.04
+FROM ubuntu:24.04
 # libclang, llvm just needed for docstrings (for development only)
 RUN export DEBIAN_FRONTEND="noninteractive" && \
     apt-get update && \
     apt-get upgrade -y && \
     apt-get -y install \
+    	black \
         casacore-dev \
         casacore-tools \
-        libclang1 \
-        clang-format-12 \
-        clang-tidy-12 \
+	clang-format-14 \
+	clang-tidy \
         cmake \
 	doxygen \
         g++ \
@@ -27,29 +27,20 @@ RUN export DEBIAN_FRONTEND="noninteractive" && \
         locales \
         make \
         ninja-build \
+	python3-breathe \
+	python3-numpy \
         python3-pip \
+	python3-pytest \
+	python3-pytest-lazy-fixture \
+	python3-sphinx \
+	python3-sphinx-rtd-theme \
         wcslib-dev \
         wget \
     && \
-    rm -rf /var/lib/apt/lists/* \
-    # The formatter needs a binary named 'clang-format', not 'clang-format-12'.
-    # Same for clang-tidy-12
-    && \
-    ln -sf clang-format-12 /usr/bin/clang-format \
-    && \
-    ln -sf clang-tidy-12 /usr/bin/clang-tidy
-RUN python3 -m pip install \
-        black \
-        breathe \
+    rm -rf /var/lib/apt/lists/*
+RUN python3 -m pip install --break-system-packages \
         cmake-format \
-        myst-parser \
-        numpy \
-        pybind11-mkdoc \
-        pytest \
-        pytest-lazy-fixture \
-        sphinx \
-        sphinx_rtd_theme \
-    ;
+        pybind11-mkdoc
 RUN locale-gen en_US.UTF-8  # Necessary for creating docstrings (Högbom)
 ENV LANG en_US.UTF-8
 ENV LANGUAGE en_US:UTF-8

scripts/run-format.sh

@@ -8,6 +8,8 @@ SOURCE_DIR=$(dirname "$0")/..
 #relative to SOURCE_DIR.
 EXCLUDE_DIRS=(external build CMake python/docstrings)
 
+CLANG_FORMAT_BINARY=clang-format-14
+
 #End script configuration.
 
 #The common formatting script has further documentation.