Merge pull request #95 from dkazanc/docsupdate

fixing api build and updating sphinx

.github/workflows/tomobar_docs.yml

@@ -1,24 +1,28 @@
 name: tomobar_docs
 
 on:
-  schedule:
-    # Run at midnight every day
-    - cron: '20 12 * * *'
-
+  workflow_dispatch:
+  pull_request:
+    branches:
+      - master
+  push:
+    branches:
+      - master
+
 jobs:
-  build-linux:
+  build-docs-publish:
     runs-on: ubuntu-latest
     defaults:
       run:
         shell: bash -el {0}
     steps:
         - name: Checkout repository code
-          uses: actions/checkout@v3
+          uses: actions/checkout@v4
 
-        - name: Setup Python 3.9
-          uses: actions/setup-python@v3
+        - name: Setup Python 3.10
+          uses: actions/setup-python@v4
           with:
-            python-version: 3.9
+            python-version: '3.10'
 
         - name: tomobar-docs
           uses: conda-incubator/setup-miniconda@v2

README.rst

@@ -1,23 +1,16 @@
 ToMoBAR's documentation
 =======================
 
-**ToMoBAR** (cite [CT2020]_, [SX2022]_) is a Python library of direct and model-based 
-regularised iterative reconstruction algorithms with a 
-plug-and-play capability. ToMoBAR offers you a selection 
-of various data models and regularisers resulting in complex 
+**ToMoBAR** (cite [CT2020]_, [SX2022]_) is a Python library of direct and model-based
+regularised iterative reconstruction algorithms with a
+plug-and-play capability. ToMoBAR offers you a selection
+of various data models and regularisers resulting in complex
 objectives for tomographic reconstruction. ToMoBAR can operate
 in GPU device-to-device fashion on CuPy arrays therefore ensuring
-a better computational efficiency. With GPU device controlling API 
+a better computational efficiency. With GPU device controlling API
 exposed it can also support multi-GPU parallel computing.
 
-Although ToMoBAR does offer a variety of reconstruction methods, 
-the FISTA algorithm [BT2009]_ specifically provides various useful modifications, e.g.:
-convergence acceleration with ordered-subsets, different 
-data fidelities: PWLS, Kullback-Leibler, Huber, Group-Huber [PM2015]_, 
-Students't [KAZ1_2017]_, and SWLS [HOA2017]_ to deal with noise and reconstruction artefacts 
-(rings, streaks). Together with the regularisers from the CCPi-Regularisation toolkit [KAZ2019]_
-one can construct up to a hundred of complex combinations for the objective function. 
-
+See more in :ref:`intro_about` or go directly to :ref:`ref_installation` and try `Demos <https://github.com/dkazanc/ToMoBAR/tree/master/Demos/Python>`_.
 
 .. figure::  _static/recsFISTA_stud.png
     :scale: 85 %

docs/source/api/tomobar.astra_wrappers.rst

@@ -1,6 +1,20 @@
-:mod:`tomobar.astra_wrappers`
-============================================
+tomobar.astra\_wrappers package
+===============================
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 4
+
+   tomobar.astra_wrappers.astra_base
+   tomobar.astra_wrappers.astra_tools2d
+   tomobar.astra_wrappers.astra_tools3d
+
+Module contents
+---------------
+
 .. automodule:: tomobar.astra_wrappers
    :members:
    :show-inheritance:
-   :undoc-members:
+   :undoc-members:

docs/source/api/tomobar.rst

@@ -7,6 +7,7 @@ Subpackages
 .. toctree::
    :maxdepth: 4
 
+   tomobar.astra_wrappers
    tomobar.cuda_kernels
    tomobar.supp
 
@@ -16,7 +17,7 @@ Submodules
 .. toctree::
    :maxdepth: 4
 
-   tomobar.astra_wrappers
+   tomobar.fourier
    tomobar.methodsDIR
    tomobar.methodsDIR_CuPy
    tomobar.methodsIR

docs/source/conf.py

@@ -1,6 +1,3 @@
-# -- General configuration ------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
 #!/usr/bin/env python
 import os
 import sys
@@ -21,9 +18,10 @@
 MOCK_MODULES = [
     "cupy",
     "astra",
+    "scipy",
+    "scipy.fftpack",
 ]
 
-
 # MOCK_MODULES = [
 #     "cupy",
 #     "skimage",
@@ -35,10 +33,34 @@
 for mod_name in MOCK_MODULES:
     sys.modules[mod_name] = mock.Mock()
 
+autodoc_mock_imports = [
+    "astra",
+    "astra.experimental",
+    "cupy",
+    "scipy",
+    "scipy.fftpack",
+    "bm3d",
+    "skimage",
+    "tomobar.astra_wrappers.astra_base",
+    "tomobar.astra_wrappers.astra_tools2d",
+    "tomobar.astra_wrappers.astra_tools3d",
+]
+
+
+class CustomMock(mock.Mock):
+    def __repr__(self):
+        return "<cp.ndarray>"
+
+
+sys.modules["cupy"] = CustomMock()
+sys.modules["numpy"] = CustomMock()
+
+
 # ------------------------------------------------------------------------------
 
-project = "Tomobar"
-# copyright = f"{date.today().year}, Diamond Light Source"
+project = "ToMoBAR"
+author = "Daniil Kazantsev"
+copyright = f"{date.today().year}, Diamond Light Source and Manchester University, UK"
 
 # Specify a base language to help assistive technology
 language = "en"
@@ -61,14 +83,15 @@
     # Add links to highlighted source code
     "sphinx.ext.viewcode",
     # Allows a grid layout and dropdown boxes
-    "sphinx_panels",
+    "sphinx_design",
     # copy to clipboard button
     "sphinx_copybutton",
+    # use jupyter notebooks
+    "nbsphinx",
     #'IPython.sphinxext.ipython_console_highlighting',
     "sphinx.ext.githubpages",
     # Generate .nojekyll file for git pages build
 ]
-
 autosummary_generate = True
 numfig = True
 template_patterns = ["_templates"]
@@ -87,14 +110,6 @@
 html_static_path = ["_static"]
 html_use_smartypants = True
 
-"""
-html_theme_options = {
-    "logo_only": True,
-    "display_version": False,
-    "githuburl": "https://github.com/dkazanc/ToMoBAR",
-}
-"""
-
 html_theme_options = {
     "logo": {
         "image_dark": "_static/tomobar_logo_dark.png",

docs/source/doc-conda-requirements.yml

@@ -1,18 +1,15 @@
 name: tomobar-docs
 channels:
   - conda-forge
-  - defaults
-  - httomo
 dependencies:
-  - python=3.10
-  - tomobar
+  - python>=3.10
   - scipy
   - sphinx
   - sphinx-book-theme
   - nbsphinx
   - pandoc
   - jinja2
-  - sphinx-panels
+  - sphinx-design
   - sphinx-copybutton
   - pyyaml
   - ipython

docs/source/howto/installation.rst

@@ -3,7 +3,10 @@
 Installation Guide
 ------------------
 ToMoBAR is a Python package with several :ref:`ref_dependencies`. To ensure its full functionality it is recommended to install them.
-It mostly relies on the GPU-enabled computations and therefore we suggest using a decent NVIDIA graphics card to support it.
+It mostly relies on the GPU-enabled computations and therefore we suggest using a decent NVIDIA graphics card to support it. ToMoBAR
+can run with `CuPy <https://cupy.dev/>`_ or using normal routines using pre-built CUDA modules of the Regularisation Toolkit.
+
+.. note:: CuPy-enabled ToMoBAR is the development in progress. Methods like FISTA can normally run several times faster, however, not every method variation is supported.
 
 .. _ref_python:
 
@@ -13,24 +16,32 @@ Python
 Install ToMoBAR as a pre-built conda Python package:
 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 
+Minimal installation that skips most of :ref:`ref_dependencies`:
+
 .. code-block:: console
 
    $ conda install -c httomo tomobar
 
-or install with the dependencies into a new environment:
+or install with the dependencies into a new environment (tested on Linux and Windows):
 
 .. code-block:: console
 
-   $ conda install -c httomo -c conda-forge tomophantom tomobar astra-toolbox ccpi-regulariser pypwt
+   $ conda install -c httomo -c conda-forge tomophantom tomobar astra-toolbox ccpi-regulariser
+
+In addition you can install CuPy :code:`conda install conda-forge::cupy` if you need CuPy-enabled modules and :code:`pip install pypwt` if you are planning to use
+wavelet regularisation.
 
-one can also try this installation, especially for other than Linux OSs:
+If the installation above does not work, one can also try:
 
 .. code-block:: console
 
    $ conda install -c httomo -c ccpi -c conda-forge tomophantom tomobar astra-toolbox ccpi-regulariser
 
+.. warning:: Note that packages installed from the CCPi channel might be of different versions and incompatible with the demos. Please create an `issue <https://github.com/dkazanc/ToMoBAR/issues>`_ on GitHub if there is a problem with an installation from the httomo channel.
+
 Install ToMoBAR from PyPi:
-+++++++++++++++++++++++++++
+++++++++++++++++++++++++++
+
 One can install ToMoBAR from PyPi, however, not all dependencies might be at PyPi yet.
 
 .. code-block:: console
@@ -40,8 +51,8 @@ One can install ToMoBAR from PyPi, however, not all dependencies might be at PyP
 
 Using conda environment:
 +++++++++++++++++++++++++
-One can also create a new conda environment by using environment yaml file,
-and then **pip** install ToMoBAR into it.
+One can also create a new conda environment by using the provided environment yaml file,
+and then **pip** install ToMoBAR into the environment.
 
 .. code-block:: console
 
@@ -60,15 +71,16 @@ This sets the development environment to work in-place on the code.
    $ conda env create --name tomobar --file conda-recipe/environment/environment.yml
    $ conda activate tomobar
    $ pip install -e .[dev] # the editable environment
-   $ pytest tests/ # all tests should pass
+   $ pytest tests/test_RecToolsDIR.py tests/test_RecToolsIR.py
+   $ pytest tests/ # you'll need CuPy to run all tests
 
 Conda builds
 +++++++++++++
 If one needs to conda-build the package, please follow the steps bellow:
 
 .. code-block:: console
 
-   $ export VERSION=$(date +%Y.%m) # OR set VERSION=2024.01 for Windows
+   $ export VERSION=$(date +%Y.%m) # OR set VERSION=2025.01 for Windows
    $ git clone [email protected]/dkazanc/ToMoBAR.git # clone the repo
    $ conda build conda-recipe/
    $ conda install path/to/the/tarball
@@ -77,6 +89,5 @@ If one needs to conda-build the package, please follow the steps bellow:
 
 Matlab
 ======
-Matlab part of ToMoBAR is not currently maintained and will be deprecated in future releases.
-The code and Demos we provide have been tested with Matlab 2018 and ASTRA-Toolbox version v1.8.3.
+.. warning:: Matlab's part of ToMoBAR is not currently maintained and will be deprecated in future releases. The code and demos were tested with Matlab 2018 and ASTRA-Toolbox version v1.8.3.
 

docs/source/howto/use.rst

@@ -2,13 +2,16 @@
 
 Using ToMoBAR
 ------------------
-In :ref:`tutorials`, we provide few examples how to reconstruct tomographic data collected using parallel-beam geometry. 
-ToMoBAR offers direct and iterative reconstructors which are build around `ASTRA-Toolbox <https://astra-toolbox.com/>`_ projection/backprojection modules, see the ASTRA wrappers at :mod:`tomobar.astra_wrappers`.
+In :ref:`tutorials`, we provide few examples how to reconstruct synthetic and real tomographic data collected with the parallel-beam geometry.
 
-The very general recipe to perform reconstruction in Python with ToMoBAR follows:
+The general recipe to perform reconstruction in Python with ToMoBAR is the following:
 
-* 1. Import a module related to the reconstruction task chosen, e.g., direct (DIR), iterative (IR), or `CuPy <https://cupy.dev/>`_-enabled.
-* 2. Instantiate the reconstructor class, while providing parameters normally related to the parallel-beam 2D and 3D scanning geometry.
-* 3. After class instantiation you will get an access to different reconstruction methods of that class. Run the selected reconstruction method providing data as an input and additional parameters, if needed.
+* 1. Import a module related to the reconstruction task chosen, e.g., direct (:code:`DIR`) modules :mod:`tomobar.methodsDIR`, iterative (:code:`IR`) :mod:`tomobar.methodsIR`,
+  or `CuPy <https://cupy.dev/>`_-enabled modules :mod:`tomobar.methodsDIR_CuPy` and :mod:`tomobar.methodsIR_CuPy`.
+* 2. Instantiate a reconstructor class while providing parameters related to the parallel-beam 2D and 3D scanning geometries.
+* 3. After instantiation you will get an access to different reconstruction methods of that class. Run selected reconstruction method providing data as an input and additional parameters.
+  For all :code:`DIR` methods parameters are passed directly, while for :code:`IR` methods you will need to form dictionaries:
+  :data:`_data_`, :data:`_algorithm_`, and :data:`_regularisation_`. See :mod:`tomobar.supp.dicts` for the list of parameters accepted.
 
-As the main aim for ToMoBAR is to reconstruct the data from the synchrotron X-ray or neutron imaging instruments, where the radiation beam is approximately parallel. So far, we do not provide API for the divergent beam geometries, however ASTRA supports it and the wrappers at :mod:`tomobar.astra_wrappers` can be extended. 
+
+.. note:: As the main aim for ToMoBAR is to reconstruct the data from the synchrotron X-ray or neutron imaging instruments, with the beam being approximately parallel. So far, we do not provide API for the divergent beam geometries, however as ASTRA supports it, the wrappers at :mod:`tomobar.astra_wrappers` can be extended. The contributions are welcome!

docs/source/introduction/about.rst

@@ -1,15 +1,20 @@
+.. _intro_about:
+
 About ToMoBAR
-*******************
+**************
+
+The general concept:
+====================
+ToMoBAR is a Python library (Matlab is not currently supported) of direct and model-based
+regularised iterative reconstruction algorithms with a plug-and-play capability.
+ToMoBAR offers you a selection of various data models and regularisers resulting in
+complex objectives for tomographic reconstruction. ToMoBAR uses ASTRA-Toolbox [VanAarle2015]_,
+for projection-backprojection parallel-beam geometry routines, which is
+a common geometry for X-ray synchrotron imaging [SX2022]_.
 
-The general concept
-=====================
-ToMoBAR is a Python library (Matlab is not currently maintained) of direct and model-based 
-regularised iterative reconstruction algorithms with a plug-and-play capability. 
-ToMoBAR offers you a selection of various data models and regularisers resulting in 
-complex objectives for tomographic reconstruction. ToMoBAR can operate
-in GPU device-to-device fashion on CuPy arrays therefore ensuring
-a better computational efficiency. With GPU device controlling API 
-exposed it can also support multi-GPU parallel computing.
+ToMoBAR can operate in GPU device-to-device fashion on CuPy arrays therefore ensuring
+a better computational efficiency. With GPU device controlling :ref:`ref_api`
+exposed it can also support multi-GPU parallel computing [CT2020]_ .
 
 .. figure::  ../_static/TomoRec_surf2.jpg
     :scale: 30 %
@@ -18,13 +23,14 @@ exposed it can also support multi-GPU parallel computing.
 What ToMoBAR can do:
 ====================
 
-* Reconstruct parallel-beam projection data in 2D and 3D using GPU-accelerated routines from ASTRA-toolbox.
-* Employ the basic direct and iterative schemes to perform reconstruction.
-* Employ advanced model-based regularised iterative schemes such as FISTA and ADMM proximal splitting algorithms.
-* The FISTA algorithm offers various modifications: 
-  convergence acceleration with ordered-subsets method,
-  different data fidelities: PWLS, Kullback-Leibler, Huber, Group-Huber [PM2015]_, Students't [KAZ1_2017]_, and SWLS [HOA2017]_
-  to deal with noise and imaging artefacts (rings, streaks).
-* Together with regularisers from the CCPi-Regularisation Toolkit [KAZ2019]_ one can construct up to a hundred of complex combinations for the objective function.
+* Reconstruct parallel-beam projection data in 2D and 3D using GPU-accelerated routines from ASTRA-toolbox [VanAarle2015]_.
+* Employ fast GPU-accelerated direct methods, such as FBP method in :mod:`tomobar.methodsDIR` and CuPy accelerated Fourier
+  reconstruction :func:`FOURIER_INV` in :mod:`tomobar.methodsDIR_CuPy`.
+* Use advanced model-based regularised iterative schemes such as FISTA and ADMM proximal splitting algorithms in :mod:`tomobar.methodsIR` or
+  even faster implementations with CuPy in :mod:`tomobar.methodsIR_CuPy`.
+* The FISTA algorithm [BT2009]_, [Xu2016]_ offers various modifications: convergence acceleration with ordered-subsets,
+  different data fidelities: PWLS, Huber, Group-Huber [PM2015]_, Students't [KAZ1_2017]_, and SWLS [HOA2017]_
+  to deal with noise and various imaging artefacts, such as, rings, streaks.
+* Combine FISTA and ADMM methods with regularisers from the CCPi-Regularisation Toolkit [KAZ2019]_. It is possible to construct different combinations of the objective function.
 
-See more on API of ToMoBAR in :ref:`ref_api`.
+See more on ToMoBAR's API in :ref:`ref_api`.