docs: add jekyll landing page

.github/workflows/README.md

@@ -1,6 +1,6 @@
 # GitHub Actions
 
-There is a single github action file with multiple jobs, which builds both the conda package and documentation, and optionally publishes the documentation: [build](https://github.com/TomographicImaging/CIL/blob/master/.github/workflows/build.yml)
+There is a single github action file with multiple jobs, which builds both the conda package and documentation, and optionally publishes the documentation: [build](./build.yml)
 
 The jobs are:
 
@@ -29,7 +29,7 @@ When opening or modifying a pull request to `master`, a single variant is built
 > The action does not publish to conda, instead this is done by jenkins. We will eventually move from jenkins to conda-forge instead.
 > When pushing to `master` or creating an [annotated tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging), *all* variants are built and tested.
 
-It looks for conda-build dependencies in the channels listed [here](https://github.com/TomographicImaging/CIL/blob/master/.github/workflows/build.yml#L118). If you add any new dependencies, the appropriate channels need to be added to this line.
+It looks for conda-build dependencies in the channels listed [here](./build.yml#L118). If you add any new dependencies, the appropriate channels need to be added to this line.
 
 > [!TIP]
 > The `conda` job builds the `*.tar.bz2` package and uploads it as an artifact called `cil-package`.
@@ -38,18 +38,29 @@ It looks for conda-build dependencies in the channels listed [here](https://gith
 
 ## docs
 
-This github action builds and optionally publishes the documentation located in [docs/source](https://github.com/TomographicImaging/CIL/tree/master/docs/source). To do this it uses a forked version of the [build-sphinx-action](https://github.com/lauramurgatroyd/build-sphinx-action).
+This github action builds and optionally publishes the documentation located in [docs/source](../../docs/source).
 
-The [docs](https://github.com/TomographicImaging/CIL/blob/master/.github/workflows/build.yml#L124) job:
+The [docs](./build.yml#L124) job:
 
-- creates a `miniconda` environment from [requirements-test.yml](https://github.com/TomographicImaging/CIL/blob/master/scripts/requirements-test.yml) and [docs_environment.yml](https://github.com/TomographicImaging/CIL/blob/master/docs/docs_environment.yml)
+- creates a `miniconda` environment from [requirements-test.yml](../../scripts/requirements-test.yml) and [docs_environment.yml](../../docs/docs_environment.yml)
 - `cmake` builds & installs CIL into the `miniconda` environment
-- builds the HTML documentation with `sphinx`
+  + builds the HTML documentation with `sphinx`
+- installs ruby dependencies from [`Gemfile`](../../docs/Gemfile)
+  + builds the HTML landing page with `jekyll`
 - uploads a `DocumentationHTML` artifact (which can be downloaded to view locally for debugging)
-- pushes the HTML documentation to the `gh-pages` branch
-  + only if pushing to `master` or tagging (skipped if pushing to a branch or a PR)
+  + pushes the HTML documentation to the `gh-pages` branch
+    * only if pushing to `master` or tagging (skipped if pushing to a branch or a PR)
 
 > [!TIP]
 > The `docs` job builds the documentation and uploads it as an artifact called `DocumentationHTML`.
 > It can be found by going to the "Actions" tab, and selecting the appropriate run of `.github/workflows/build.yml`, or by clicking on the tick on the action in the "All checks have passed/failed" section of a PR. When viewing the "Summary" for the run of the action, there is an "Artifact" section at the bottom of the page.
-> Clicking on `DocumentationHTML` allows you to download a zip folder containing the built HTML files. This allows you to preview the documentation site before it is published.
+> Click on `DocumentationHTML` to download a zip archive of the built HTML files.
+> It must be extracted into a `CIL` subfolder to properly render locally:
+>
+> ```sh
+> mkdir CIL
+> unzip -d CIL DocumentationHTML.zip
+> python -m http.server
+> ```
+>
+> Then open a browser and navigate to <http://localhost:8000/CIL/> to view the documentation.

.github/workflows/build.yml

@@ -129,7 +129,7 @@ jobs:
         name: cil-package
         path: recipe/linux-64/cil*
   docs:
-    defaults: {run: {shell: 'bash -el {0}'}}
+    defaults: {run: {shell: 'bash -el {0}', working-directory: docs}}
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
@@ -139,14 +139,19 @@ jobs:
         ref: ${{ github.event.pull_request.head.sha || github.ref }} # fix SHA
     - uses: conda-incubator/setup-miniconda@v3
       with: {python-version: 3.11}
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '3.2'
+        bundler-cache: true
+        cache-version: 0
     - name: install dependencies
       run: |
-        cd docs
         conda install -c conda-forge -yq conda-merge
         conda-merge ../scripts/requirements-test.yml docs_environment.yml > environment.yml
         conda env update -n test
         conda list
     - name: build cil
+      working-directory: .
       run: |
         cmake -S . -B ./build -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCONDA_BUILD=ON -DCMAKE_INSTALL_PREFIX="$CONDA_PREFIX"
         cmake --build ./build --target install
@@ -155,17 +160,17 @@ jobs:
       with:
         path: docs/build
         ref: gh-pages
-    - name: update docs
+    - id: pages
+      uses: actions/configure-pages@v5
+    - name: update web pages (jekyll)
+      run: make JEKYLLOPTS="--baseurl ${{ steps.pages.outputs.base_path }}" web-deps web
+      env: {JEKYLL_ENV: production}
+    - name: update docs pages (sphinx)
       run: |
-        cd docs
         docs_dir="${{ github.ref_name }}"
         docs_dir="${docs_dir//\//_}"
         if test "$docs_dir" = master; then docs_dir=nightly; fi
-        rm -rf "build/$docs_dir"
-        ./mkdemos.py
-        sphinx-build -b dirhtml source "build/$docs_dir"
-        sed 's#DESTINATION#nightly#g' .redirect-template.html > build/index.html
-        ./mkversions.py
+        make BUILDSUBDIR="$docs_dir" dirhtml
     - uses: actions/upload-artifact@v4
       with:
         name: DocumentationHTML

.gitignore

@@ -4,4 +4,3 @@
 /Wrappers/Python/cil/version.py
 /Wrappers/Python/setup.py
 __pycache__/
-/docs/build/

CITATION.cff

@@ -1,46 +1,46 @@
 cff-version: 1.2.0
 message: "If you use this software, please cite the software itself via zenodo as below, plus a CIL article, please see the CIL README for more details: https://github.com/TomographicImaging/CIL"
-abstract: "The Core Imaging Library (CIL) is an open-source Python framework for tomographic imaging 
-           with particular emphasis on reconstruction of challenging datasets. Conventional filtered 
-           backprojection reconstruction tends to be insufficient for highly noisy, incomplete, non-standard
-           or multichannel data arising for example in dynamic, spectral and in situ tomography. CIL
-           provides an extensive modular optimisation framework for prototyping reconstruction methods
-           including sparsity and total variation regularisation, as well as tools for loading, preprocessing
-           and visualising tomographic data."
+abstract: >
+  The Core Imaging Library (CIL) is an open-source Python framework for tomographic imaging
+  with particular emphasis on reconstruction of challenging datasets. Conventional filtered
+  backprojection reconstruction tends to be insufficient for highly noisy, incomplete, non-standard
+  or multichannel data arising for example in dynamic, spectral and in situ tomography. CIL
+  provides an extensive modular optimisation framework for prototyping reconstruction methods
+  including sparsity and total variation regularisation, as well as tools for loading, preprocessing
+  and visualising tomographic data.
 authors:
-  - family-names: Pasca
-    given-names: Edoardo
-  - family-names: Jørgensen
-    given-names: Jakob Sauer
-  - family-names: Papoutsellis
-    given-names: Evangelos
-  - family-names: Ametova
-    given-names: Evelina
-  - family-names: Fardell
-    given-names: Gemma
-  - family-names: Thielemans
-    given-names: Kris
-  - family-names: Murgatroyd
-    given-names: Laura
-  - family-names: Duff
-    given-names: Margaret
-  - family-names: da Costa-Luis
-    given-names: Casper
-  - family-names: Robarts
-    given-names: Hannah
-title: "Core Imaging Library (CIL)"
-doi: 10.5281/zenodo.4746198
-date-released: "08-01-18"
+- family-names: Pasca
+  given-names: Edoardo
+- family-names: Jørgensen
+  given-names: Jakob Sauer
+- family-names: Papoutsellis
+  given-names: Evangelos
+- family-names: Ametova
+  given-names: Evelina
+- family-names: Fardell
+  given-names: Gemma
+- family-names: Thielemans
+  given-names: Kris
+- family-names: Murgatroyd
+  given-names: Laura
+- family-names: Duff
+  given-names: Margaret
+- family-names: da Costa-Luis
+  given-names: Casper
+- family-names: Robarts
+  given-names: Hannah
+title: Core Imaging Library (CIL)
+date-released: '2018-01-08'
 identifiers:
-  - description: "This is the collection of archived snapshots of all versions of the Core Imaging Library"
-    type: doi
-    value: 10.5281/zenodo.4746198
+- description: This is the collection of archived snapshots of all versions of the Core Imaging Library
+  type: doi
+  value: 10.5281/zenodo.4746198
 keywords:
-  - "tomographic imaging"
-  - research
-  - tomography
-  - reconstruction
-  - imaging
-  - hyperspectral
-  - optimisation
+- tomographic imaging
+- research
+- tomography
+- reconstruction
+- imaging
+- hyperspectral
+- optimisation
 license: Apache-2.0

README.md

@@ -105,7 +105,7 @@ Jupyter Notebooks usage examples without any local installation are provided in
 In case of development it is useful to be able to build the software directly. You should clone this repository as
 
 ```sh
-git clone --recurse-submodule git@github.com:TomographicImaging/CIL.git
+git clone --recurse-submodule git@github.com:TomographicImaging/CIL
 ```
 
 The use of `--recurse-submodule` is necessary if the user wants the examples data to be fetched (they are needed by the unit tests). We have moved such data, previously hosted in this repo at `Wrappers/Python/data` to the [CIL-data](https://github.com/TomographicImaging/CIL-Data) repository and linked it to this one as submodule. If the data is not available it can be fetched in an already cloned repository as

Wrappers/Python/CMake/setup.py.in

@@ -50,10 +50,9 @@ setup(
 
 
     # metadata for upload to PyPI
-    author="CCPi developers",
-    maintainer="Edoardo Pasca",
+    maintainer="CIL developers",
     maintainer_email="edoardo.pasca@stfc.ac.uk",
-    description='CCPi Core Imaging Library',
+    description='Core Imaging Library',
     license="Apache v2.0",
     keywords="Python Framework",
     url="http://www.ccpi.ac.uk/cil",

docs/.gitignore

@@ -1,2 +1,9 @@
 /source/demos/
 /source/demos.rst
+/build/
+/_site/
+.sass-cache/
+.jekyll-cache/
+.jekyll-metadata/
+/.bundle/
+/vendor/

docs/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+gem "jekyll"
+group :jekyll_plugins do
+  gem 'jekyll-remote-theme'
+end

docs/Gemfile.lock

@@ -0,0 +1,130 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.6)
+      public_suffix (>= 2.0.2, < 6.0)
+    colorator (1.1.0)
+    concurrent-ruby (1.2.3)
+    em-websocket (0.5.3)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0)
+    eventmachine (1.2.7)
+    ffi (1.16.3)
+    forwardable-extended (2.6.0)
+    google-protobuf (4.26.1)
+      rake (>= 13)
+    google-protobuf (4.26.1-aarch64-linux)
+      rake (>= 13)
+    google-protobuf (4.26.1-arm64-darwin)
+      rake (>= 13)
+    google-protobuf (4.26.1-x86-linux)
+      rake (>= 13)
+    google-protobuf (4.26.1-x86_64-darwin)
+      rake (>= 13)
+    google-protobuf (4.26.1-x86_64-linux)
+      rake (>= 13)
+    http_parser.rb (0.8.0)
+    i18n (1.14.4)
+      concurrent-ruby (~> 1.0)
+    jekyll (4.3.3)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      em-websocket (~> 0.5)
+      i18n (~> 1.0)
+      jekyll-sass-converter (>= 2.0, < 4.0)
+      jekyll-watch (~> 2.0)
+      kramdown (~> 2.3, >= 2.3.1)
+      kramdown-parser-gfm (~> 1.0)
+      liquid (~> 4.0)
+      mercenary (>= 0.3.6, < 0.5)
+      pathutil (~> 0.9)
+      rouge (>= 3.0, < 5.0)
+      safe_yaml (~> 1.0)
+      terminal-table (>= 1.8, < 4.0)
+      webrick (~> 1.7)
+    jekyll-remote-theme (0.4.3)
+      addressable (~> 2.0)
+      jekyll (>= 3.5, < 5.0)
+      jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0)
+      rubyzip (>= 1.3.0, < 3.0)
+    jekyll-sass-converter (3.0.0)
+      sass-embedded (~> 1.54)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    kramdown (2.4.0)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    liquid (4.0.4)
+    listen (3.9.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    mercenary (0.4.0)
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
+    public_suffix (5.0.5)
+    rake (13.2.1)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rexml (3.2.6)
+    rouge (4.2.1)
+    rubyzip (2.3.2)
+    safe_yaml (1.0.5)
+    sass-embedded (1.75.0-aarch64-linux-android)
+      google-protobuf (>= 3.25, < 5.0)
+    sass-embedded (1.75.0-aarch64-linux-gnu)
+      google-protobuf (>= 3.25, < 5.0)
+    sass-embedded (1.75.0-aarch64-linux-musl)
+      google-protobuf (>= 3.25, < 5.0)
+    sass-embedded (1.75.0-arm-linux-androideabi)
+      google-protobuf (>= 3.25, < 5.0)
+    sass-embedded (1.75.0-arm-linux-gnueabihf)
+      google-protobuf (>= 3.25, < 5.0)
+    sass-embedded (1.75.0-arm-linux-musleabihf)
+      google-protobuf (>= 3.25, < 5.0)
+    sass-embedded (1.75.0-arm64-darwin)
+      google-protobuf (>= 3.25, < 5.0)
+    sass-embedded (1.75.0-x86-linux-android)
+      google-protobuf (>= 3.25, < 5.0)
+    sass-embedded (1.75.0-x86-linux-gnu)
+      google-protobuf (>= 3.25, < 5.0)
+    sass-embedded (1.75.0-x86-linux-musl)
+      google-protobuf (>= 3.25, < 5.0)
+    sass-embedded (1.75.0-x86_64-darwin)
+      google-protobuf (>= 3.25, < 5.0)
+    sass-embedded (1.75.0-x86_64-linux-android)
+      google-protobuf (>= 3.25, < 5.0)
+    sass-embedded (1.75.0-x86_64-linux-gnu)
+      google-protobuf (>= 3.25, < 5.0)
+    sass-embedded (1.75.0-x86_64-linux-musl)
+      google-protobuf (>= 3.25, < 5.0)
+    terminal-table (3.0.2)
+      unicode-display_width (>= 1.1.1, < 3)
+    unicode-display_width (2.5.0)
+    webrick (1.8.1)
+
+PLATFORMS
+  aarch64-linux
+  aarch64-linux-android
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-androideabi
+  arm-linux-gnueabihf
+  arm-linux-musleabihf
+  arm64-darwin
+  x86-linux
+  x86-linux-android
+  x86-linux-gnu
+  x86-linux-musl
+  x86_64-darwin
+  x86_64-linux-android
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  jekyll
+  jekyll-remote-theme
+
+BUNDLED WITH
+   2.5.9