From 3097a8205a6c345dd5eee09d27105f7d645bccf8 Mon Sep 17 00:00:00 2001 From: Casper da Costa-Luis Date: Fri, 9 Feb 2024 15:31:44 +0000 Subject: [PATCH 01/17] docs: add jekyll landing page --- .github/workflows/build.yml | 16 +++- .gitignore | 1 - docs/.gitignore | 7 ++ docs/Gemfile | 6 ++ docs/Gemfile.lock | 130 ++++++++++++++++++++++++++++++ docs/mkversions.py | 4 +- docs/pages/_config.yml | 109 +++++++++++++++++++++++++ docs/pages/_data/authors.yml | 6 ++ docs/pages/_data/navigation.yml | 39 +++++++++ docs/pages/_data/network.yml | 17 ++++ docs/pages/_data/services.yml | 16 ++++ docs/pages/_data/socialmedia.yml | 1 + docs/pages/_includes/_footer.html | 79 ++++++++++++++++++ docs/pages/index.md | 3 + 14 files changed, 430 insertions(+), 4 deletions(-) create mode 100644 docs/Gemfile create mode 100644 docs/Gemfile.lock create mode 100644 docs/pages/_config.yml create mode 100644 docs/pages/_data/authors.yml create mode 100644 docs/pages/_data/navigation.yml create mode 100644 docs/pages/_data/network.yml create mode 100644 docs/pages/_data/services.yml create mode 100644 docs/pages/_data/socialmedia.yml create mode 100644 docs/pages/_includes/_footer.html create mode 100644 docs/pages/index.md diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 776f6dcc43..1e72e4aa67 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -139,6 +139,11 @@ 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 @@ -155,17 +160,26 @@ jobs: with: path: docs/build ref: gh-pages + - id: pages + uses: actions/configure-pages@v5 - name: update docs run: | cd docs + # landing page (jekyll) + bundle install + bundle exec jekyll build -s pages --baseurl "${{ steps.pages.outputs.base_path }}" + rm -rf build/.git build/assets build/index.html + mv _site/* build/ + # docs pages (sphinx) 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 + env: + JEKYLL_ENV: production - uses: actions/upload-artifact@v4 with: name: DocumentationHTML diff --git a/.gitignore b/.gitignore index 4a11c2ae07..982d81a0f3 100644 --- a/.gitignore +++ b/.gitignore @@ -4,4 +4,3 @@ /Wrappers/Python/cil/version.py /Wrappers/Python/setup.py __pycache__/ -/docs/build/ diff --git a/docs/.gitignore b/docs/.gitignore index 40cfac2a20..6b8314eacb 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,2 +1,9 @@ /source/demos/ /source/demos.rst +/build/ +/_site/ +.sass-cache/ +.jekyll-cache/ +.jekyll-metadata/ +/.bundle/ +/vendor/ diff --git a/docs/Gemfile b/docs/Gemfile new file mode 100644 index 0000000000..43d977b07b --- /dev/null +++ b/docs/Gemfile @@ -0,0 +1,6 @@ +source "https://rubygems.org" + +gem "jekyll" +group :jekyll_plugins do + gem 'jekyll-remote-theme' +end diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock new file mode 100644 index 0000000000..23687f55ad --- /dev/null +++ b/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.6 diff --git a/docs/mkversions.py b/docs/mkversions.py index be9d3ebb64..3325f47b8d 100755 --- a/docs/mkversions.py +++ b/docs/mkversions.py @@ -8,14 +8,14 @@ baseurl = f'/{getenv("GITHUB_REPOSITORY", "").split("/", 1)[-1]}/'.replace("//", "/") build = Path(__file__).parent / "build" versions = [{ - "name": str(i.name), + "name": i.name, "version": re.search( "VERSION: '(.*)'", (i / "_static" / "documentation_options.js").read_text(), flags=re.M).group(1), "url": f"{baseurl}{i.name}/" } -for i in build.glob("[a-zA-Z]*") if i.is_dir()] +for i in build.glob("[a-zA-Z]*") if i.is_dir() if i.name != "assets"] tags = [v for v in versions if v["name"] == "v" + v["version"]] try: diff --git a/docs/pages/_config.yml b/docs/pages/_config.yml new file mode 100644 index 0000000000..6550788caf --- /dev/null +++ b/docs/pages/_config.yml @@ -0,0 +1,109 @@ +# jekyll config +remote_theme: Phlow/feeling-responsive +title: CIL +slogan: The Core Imaging Library +description: | + CIL is a versatile python framework for tomographic imaging. +
+ CCPi is funded by the EPSRC grant EP/T026677/1. +
+ CCPi acknowledges previous funding support by the EPSRC grants EP/J010456/1 + and EP/M022498/1. +
+ The CCPi Flagship "A Reconstruction Toolkit for Multichannel CT" was funded by the + EPSRC grant EP/P02226X/1. +
+subfooter: > + + + + +
+ Copyright © UKRI STFC SCD +author: ccpi-devs +#url: 'https://tomographicimaging.github.io' +baseurl: '' +improve_content: https://github.com/TomographicImaging/CIL/edit/master/docs +# e.g. ![Image Text]({{ site.urlimg }}image.jpg) +urlimg: 'https://ccpi.ac.uk/wp-content/uploads/' +logo: "https://ccpi.ac.uk/wp-content/uploads/2022/11/CIL-logo-RGB.svg" # ideally 600x80 pixels +language: en-GB +plugins: +- jekyll-remote-theme + +# Theme works best with Kramdown (using the table of contents function) +#markdown: kramdown +permalink: pretty +highlight: rouge +excerpt_separator: "" +#include: ['.htaccess'] +exclude: +- .sass-cache +- Gemfile +- Gemfile.lock +- LICENSE +- README.md +- INSTALL.md +- vendor +# sphinx +- docs_environment.yml +- make.bat +- Makefile +- mkversions.py +- .redirect-template.html +- source + +# http://jch.penibelst.de +compress_html: + clippings: all + comments: [""] + endings: all + profile: false + ignore: + envs: [development] + +defaults: +- scope: + path: '' # all files + type: pages + values: + show_meta: false + # sidebar: # left, right (default undefined means none) + comments: false + author: CCPi Developers + +#google_site_verification: '' +#bing_webmastertools_id: '' +#yandex_site_verification: '' +#alexa_verify_id: '' + +# https://mathiasbynens.be/notes/touch-icons +favicon-32x32: 'https://ccpi.ac.uk/wp-content/uploads/2022/11/cropped-CCPi_Logo_Icon_Only-32x32.png' +#msapplication_tilecolor: '#fabb00' + +# http://j.mp/fb_optimize +og_image: 'https://ccpi.ac.uk/wp-content/uploads/2022/11/CIL-logo-RGB.svg' +og_locale: en_EN +og_type: website +#disqus_shortname: + +# http://sass-lang.com/ +# http://jekyllrb.com/docs/assets/#sassscss +sass: + sass_dir: _sass + style: :compressed + +#google_analytics_tracking_id: + +# https://www.tawk.to/knowledgebase/ +#tawkto_embed_uri: + +# https://github.com/asciidoctor/jekyll-asciidoc +# https://github.com/asciidoctor +#asciidoctor-enabled: false +#asciidoctor: +# description: +# attributes: +# source-highlighter: coderay +# coderay-css: style +# icons: font diff --git a/docs/pages/_data/authors.yml b/docs/pages/_data/authors.yml new file mode 100644 index 0000000000..eb1fd93730 --- /dev/null +++ b/docs/pages/_data/authors.yml @@ -0,0 +1,6 @@ +# https://github.com/Phlow/feeling-responsive/blob/gh-pages/_data/authors.yml +# http://blog.sorryapp.com/blogging-with-jekyll/2014/02/06/adding-authors-to-your-jekyll-site.html +ccpi-devs: + name: CCPi Developers + siterole: "webmaster, developer, copywriter, designer" + uri: https://github.com/TomographicImaging/CIL/graphs/contributors diff --git a/docs/pages/_data/navigation.yml b/docs/pages/_data/navigation.yml new file mode 100644 index 0000000000..096ac10cc9 --- /dev/null +++ b/docs/pages/_data/navigation.yml @@ -0,0 +1,39 @@ +# https://github.com/Phlow/feeling-responsive/blob/gh-pages/_data/navigation.yml +- title: Home + url: "/" + side: left +- title: Documentation + url: "/nightly/" + side: left + dropdown: + - title: Documentation + url: "/nightly/" + - title: Changelog + url: "https://github.com/TomographicImaging/CIL/releases" + - title: Developer Guide + url: "/nightly/developer_guide/" +- title: Launch Demos + url: "https://mybinder.org/v2/gh/TomographicImaging/CIL-Demos/HEAD?urlpath=lab/tree/binder%2Findex.ipynb" + side: left +- title: GitHub + url: "https://github.com/TomographicImaging" + side: right + dropdown: + - title: CIL + url: "https://github.com/TomographicImaging/CIL" + - title: CIL-Demos + url: "https://github.com/TomographicImaging/CIL-Demos" +- title: Contact + url: "/nightly/#contacts" + side: right + dropdown: + - title: Discord + url: "https://discord.gg/9NTWu9MEGq" + - title: Member Mailing List + url: "https://www.jiscmail.ac.uk/cgi-bin/webadmin?A0=CCPI-MEMBERS" + - title: Developer Mailing List + url: "https://www.jiscmail.ac.uk/cgi-bin/webadmin?A0=CCPI-DEVEL" + - title: Zenodo Community + url: "https://zenodo.org/communities/ccpi/about" + - title: LinkedIn + url: "https://www.linkedin.com/groups/9090791/" diff --git a/docs/pages/_data/network.yml b/docs/pages/_data/network.yml new file mode 100644 index 0000000000..1ff2d35abe --- /dev/null +++ b/docs/pages/_data/network.yml @@ -0,0 +1,17 @@ +# https://github.com/Phlow/feeling-responsive/blob/gh-pages/_data/network.yml +- menu_name: Thanks +- name: CoSeC + url: "https://www.scd.stfc.ac.uk/Pages/CoSeC.aspx" + title: "Computational Science Centre for Research Communities" +- name: UKRI + url: "https://www.ukri.org" + title: "UK Research and Innovation" +- name: STFC + url: "https://stfc.ac.uk" + title: "Science and Technology Facilities Council" +- name: EPSRC + url: "https://epsrc.ac.uk" + title: "Engineering and Physical Sciences Research Council" +- name: Manchester + url: "https://www.manchester.ac.uk" + title: "University of Manchester" diff --git a/docs/pages/_data/services.yml b/docs/pages/_data/services.yml new file mode 100644 index 0000000000..16dc75496b --- /dev/null +++ b/docs/pages/_data/services.yml @@ -0,0 +1,16 @@ +# https://github.com/Phlow/feeling-responsive/blob/gh-pages/_data/services.yml +- menu_name: Contact +- name: Discord + url: "https://discord.gg/9NTWu9MEGq" +- name: Member List + title: Member Mailing List + url: "https://www.jiscmail.ac.uk/cgi-bin/webadmin?A0=CCPI-MEMBERS" +- name: Developer List + title: Developer Mailing List + url: "https://www.jiscmail.ac.uk/cgi-bin/webadmin?A0=CCPI-DEVEL" +- name: Zenodo + title: Zenodo Community + url: "https://zenodo.org/communities/ccpi/about" +- name: LinkedIn + title: LinkedIn Group + url: "https://www.linkedin.com/groups/9090791/" diff --git a/docs/pages/_data/socialmedia.yml b/docs/pages/_data/socialmedia.yml new file mode 100644 index 0000000000..0bc0d094cc --- /dev/null +++ b/docs/pages/_data/socialmedia.yml @@ -0,0 +1 @@ +# https://github.com/Phlow/feeling-responsive/blob/gh-pages/_data/socialmedia.yml diff --git a/docs/pages/_includes/_footer.html b/docs/pages/_includes/_footer.html new file mode 100644 index 0000000000..f9584adaaf --- /dev/null +++ b/docs/pages/_includes/_footer.html @@ -0,0 +1,79 @@ + +
+
+ +
+
+ + + diff --git a/docs/pages/index.md b/docs/pages/index.md new file mode 100644 index 0000000000..e53fa377bd --- /dev/null +++ b/docs/pages/index.md @@ -0,0 +1,3 @@ +--- +layout: frontpage +--- From 4ded4b5520f33e90308ca9bb752aa3e7031883c7 Mon Sep 17 00:00:00 2001 From: Casper da Costa-Luis Date: Fri, 9 Feb 2024 22:06:31 +0000 Subject: [PATCH 02/17] example content --- docs/pages/index.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/docs/pages/index.md b/docs/pages/index.md index e53fa377bd..c91ed1b20b 100644 --- a/docs/pages/index.md +++ b/docs/pages/index.md @@ -1,3 +1,47 @@ --- +# https://github.com/Phlow/feeling-responsive/blob/gh-pages/pages/pages-root-folder/index.md layout: frontpage +header: + image_fullwidth: 2022/08/front-page-1125x800.png +widget1: + title: Examples + url: 'https://mybinder.org/v2/gh/TomographicImaging/CIL-Demos/HEAD?urlpath=lab/tree/binder%2Findex.ipynb' + image: 2022/04/walnut_training.png + text: > + We have a repository with a large collection of Jupyter Notebooks which cover a wide range of topics, from basic usage to advanced reconstructions with iterative methods. +
+ Some examples without any local installation are provided in Binder. + Please click the button below to try them immediately in your browser. +widget2: + title: CIL Documentation + url: '/nightly/' + image: 2022/11/CIL-logo-RGB.svg + text: > + CIL has a live documentation which gets updated regularly and built nightly. + We suggest to download and read the open access articles below, which provide very detailed information about CIL structure and usage. +widget3: + title: Papers + url: 'https://github.com/TomographicImaging/Paper-2021-RSTA-CIL-Part-II' + image: 2022/10/RSTA_cover.png + text: > + Jørgensen JS et al. 2021 Core Imaging Library – Part I: a versatile python framework for tomographic imaging. Phil. Trans. R. Soc. A 20200192. +
+ The code to reproduce the results of the paper can be found at Paper-2021-RSTA-CIL-Part-I. +
+
+ Papoutsellis E et al. 2021 Core Imaging Library – Part II: multichannel reconstruction for dynamic and spectral tomography. Phil. Trans. R. Soc. A 20200193. +
+ The code to reproduce the results of the paper can be found at at Paper-2021-RSTA-CIL-Part-II. +callforaction: + url: https://ccpi.ac.uk/training + text: Training + style: alert --- + +## A versatile python framework for tomographic imaging + +CIL is an **open-source** mainly Python framework for tomographic imaging for *cone* and *parallel beam* geometries. It comes with tools for **loading**, **preprocessing**, **reconstructing** and **visualising** tomographic data. + +CIL provides **optimised** standard methods such as *Filtered Back Projection* and *FDK* and an extensive **modular optimisation framework** for prototyping reconstruction methods including *sparsity* and *total variation* regularisation, useful when conventional filtered backprojection reconstruction do not lead to satisfactory results, as in highly noisy, incomplete, non-standard or multichannel data arising for example in *dynamic*, *spectral* and *in situ* tomography. + +CIL is open-source software released under the [Apache v2.0 licence](http://www.apache.org/licenses/LICENSE-2.0.html). From 3d59be69979c2e974854e51799098b660f96dc17 Mon Sep 17 00:00:00 2001 From: Casper da Costa-Luis Date: Tue, 13 Feb 2024 17:17:26 +0000 Subject: [PATCH 03/17] fix images & links --- docs/mkversions.py | 2 +- docs/pages/_config.yml | 11 +++-------- docs/pages/_includes/_favicon.html | 1 + docs/pages/index.md | 9 +++++---- 4 files changed, 10 insertions(+), 13 deletions(-) create mode 100644 docs/pages/_includes/_favicon.html diff --git a/docs/mkversions.py b/docs/mkversions.py index 3325f47b8d..ebef16d502 100755 --- a/docs/mkversions.py +++ b/docs/mkversions.py @@ -15,7 +15,7 @@ flags=re.M).group(1), "url": f"{baseurl}{i.name}/" } -for i in build.glob("[a-zA-Z]*") if i.is_dir() if i.name != "assets"] +for i in build.glob("[a-zA-Z0-9]*") if i.is_dir() if i.name != "assets"] tags = [v for v in versions if v["name"] == "v" + v["version"]] try: diff --git a/docs/pages/_config.yml b/docs/pages/_config.yml index 6550788caf..37310f0845 100644 --- a/docs/pages/_config.yml +++ b/docs/pages/_config.yml @@ -21,11 +21,10 @@ subfooter: >
Copyright © UKRI STFC SCD author: ccpi-devs -#url: 'https://tomographicimaging.github.io' -baseurl: '' +url: '' # https://tomographicimaging.github.io +baseurl: '' # /CIL improve_content: https://github.com/TomographicImaging/CIL/edit/master/docs -# e.g. ![Image Text]({{ site.urlimg }}image.jpg) -urlimg: 'https://ccpi.ac.uk/wp-content/uploads/' +urlimg: '' logo: "https://ccpi.ac.uk/wp-content/uploads/2022/11/CIL-logo-RGB.svg" # ideally 600x80 pixels language: en-GB plugins: @@ -77,10 +76,6 @@ defaults: #yandex_site_verification: '' #alexa_verify_id: '' -# https://mathiasbynens.be/notes/touch-icons -favicon-32x32: 'https://ccpi.ac.uk/wp-content/uploads/2022/11/cropped-CCPi_Logo_Icon_Only-32x32.png' -#msapplication_tilecolor: '#fabb00' - # http://j.mp/fb_optimize og_image: 'https://ccpi.ac.uk/wp-content/uploads/2022/11/CIL-logo-RGB.svg' og_locale: en_EN diff --git a/docs/pages/_includes/_favicon.html b/docs/pages/_includes/_favicon.html new file mode 100644 index 0000000000..29b4af8b41 --- /dev/null +++ b/docs/pages/_includes/_favicon.html @@ -0,0 +1 @@ + diff --git a/docs/pages/index.md b/docs/pages/index.md index c91ed1b20b..b14adacdca 100644 --- a/docs/pages/index.md +++ b/docs/pages/index.md @@ -2,11 +2,12 @@ # https://github.com/Phlow/feeling-responsive/blob/gh-pages/pages/pages-root-folder/index.md layout: frontpage header: - image_fullwidth: 2022/08/front-page-1125x800.png + image_fullwidth: https://ccpi.ac.uk/wp-content/uploads/2022/08/front-page-1125x800.png # ideally 600x80 pixels + title: 'CIL - Core Imaging Library' widget1: title: Examples url: 'https://mybinder.org/v2/gh/TomographicImaging/CIL-Demos/HEAD?urlpath=lab/tree/binder%2Findex.ipynb' - image: 2022/04/walnut_training.png + image: https://ccpi.ac.uk/wp-content/uploads/2022/04/walnut_training.png text: > We have a repository with a large collection of Jupyter Notebooks which cover a wide range of topics, from basic usage to advanced reconstructions with iterative methods.
@@ -15,14 +16,14 @@ widget1: widget2: title: CIL Documentation url: '/nightly/' - image: 2022/11/CIL-logo-RGB.svg + image: https://ccpi.ac.uk/wp-content/uploads/2022/11/CIL-logo-RGB.svg text: > CIL has a live documentation which gets updated regularly and built nightly. We suggest to download and read the open access articles below, which provide very detailed information about CIL structure and usage. widget3: title: Papers url: 'https://github.com/TomographicImaging/Paper-2021-RSTA-CIL-Part-II' - image: 2022/10/RSTA_cover.png + image: https://ccpi.ac.uk/wp-content/uploads/2022/10/RSTA_cover.png text: > Jørgensen JS et al. 2021 Core Imaging Library – Part I: a versatile python framework for tomographic imaging. Phil. Trans. R. Soc. A 20200192.
From f6f4f29ffe87a3f86898949f4264e675e5ed26c5 Mon Sep 17 00:00:00 2001 From: Casper da Costa-Luis Date: Tue, 13 Feb 2024 17:49:19 +0000 Subject: [PATCH 04/17] refactor image footers --- docs/pages/_config.yml | 7 ------- docs/pages/_data/network.yml | 8 ++++++++ docs/pages/_includes/_footer.html | 9 ++++++++- 3 files changed, 16 insertions(+), 8 deletions(-) diff --git a/docs/pages/_config.yml b/docs/pages/_config.yml index 37310f0845..383899bad8 100644 --- a/docs/pages/_config.yml +++ b/docs/pages/_config.yml @@ -13,13 +13,6 @@ description: | The CCPi Flagship "A Reconstruction Toolkit for Multichannel CT" was funded by the EPSRC grant EP/P02226X/1.
-subfooter: > - - - - -
- Copyright © UKRI STFC SCD author: ccpi-devs url: '' # https://tomographicimaging.github.io baseurl: '' # /CIL diff --git a/docs/pages/_data/network.yml b/docs/pages/_data/network.yml index 1ff2d35abe..ef0c532dad 100644 --- a/docs/pages/_data/network.yml +++ b/docs/pages/_data/network.yml @@ -3,15 +3,23 @@ - name: CoSeC url: "https://www.scd.stfc.ac.uk/Pages/CoSeC.aspx" title: "Computational Science Centre for Research Communities" + image: "https://ccpi.ac.uk/wp-content/uploads/2022/10/CoSec_Transparent-002.png" + image_width: 85 - name: UKRI url: "https://www.ukri.org" title: "UK Research and Innovation" - name: STFC url: "https://stfc.ac.uk" title: "Science and Technology Facilities Council" + image: "https://ccpi.ac.uk/wp-content/uploads/2022/10/STFC_White_Text-2.png" + image_width: 249 - name: EPSRC url: "https://epsrc.ac.uk" title: "Engineering and Physical Sciences Research Council" + image: "https://ccpi.ac.uk/wp-content/uploads/2022/10/epsrc.png" + image_width: 256 - name: Manchester url: "https://www.manchester.ac.uk" title: "University of Manchester" + image: "https://ccpi.ac.uk/wp-content/uploads/2022/10/TAB_col_background_manc-300x127.png" + image_width: 151 diff --git a/docs/pages/_includes/_footer.html b/docs/pages/_includes/_footer.html index f9584adaaf..3878830ddc 100644 --- a/docs/pages/_includes/_footer.html +++ b/docs/pages/_includes/_footer.html @@ -60,7 +60,14 @@
{{ network_item.menu_name }}
@@ -28,7 +28,7 @@
{{ service_item.menu_name }}
    {% for service_item in site.data.services %} - {% if service_item.url contains 'http' %}{% assign domain = '' %}{% else %}{% capture domain %}{{ site.url }}{{ site.baseurl }}{% endcapture %}{% endif %} + {% if service_item.url contains 'http' %}{% assign domain = '' %}{% else %}{% assign domain = site.url + site.baseurl %}{% endif %}
  • {{ service_item.name }}
    • @@ -46,7 +46,7 @@
    {{ network_item.menu_name }}
      {% for network_item in site.data.network %} - {% if network_item.url contains 'http' %}{% assign domain = '' %}{% else %}{% capture domain %}{{ site.url }}{{ site.baseurl }}{% endcapture %}{% endif %} + {% if network_item.url contains 'http' %}{% assign domain = '' %}{% else %}{% assign domain = site.url + site.baseurl %}{% endif %}
    • {{ network_item.name }}
      • diff --git a/docs/pages/about.md b/docs/pages/about.md new file mode 100644 index 0000000000..be7600cee6 --- /dev/null +++ b/docs/pages/about.md @@ -0,0 +1,8 @@ +--- +layout: page-fullwidth +header: false +title: About the Core Imaging Library (CIL) +teaser: A versatile python framework for tomographic imaging +--- + +WiP From e3ad6652aeb3502e7a46c3c82a453a8f08195985 Mon Sep 17 00:00:00 2001 From: Casper da Costa-Luis Date: Wed, 14 Feb 2024 20:16:20 +0000 Subject: [PATCH 07/17] docs link back to landing --- docs/source/conf.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index 8538ec6fe6..4331fad909 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -71,6 +71,8 @@ "logo": { "image_light": "https://ccpi.ac.uk/wp-content/uploads/2022/11/CIL-logo-RGB.svg", "image_dark": "https://ccpi.ac.uk/wp-content/uploads/2022/11/CIL-logo-RGB-reversed.svg", + "link": "/", + "alt_text": "CIL - Home", }, "show_version_warning_banner": True, "header_links_before_dropdown": 9, From 310ba5d9519106cd67c21efbabb5de32bf2a2a96 Mon Sep 17 00:00:00 2001 From: Casper da Costa-Luis Date: Wed, 14 Feb 2024 21:26:37 +0000 Subject: [PATCH 08/17] make -C docs --- .github/workflows/build.yml | 13 ++-------- docs/Makefile | 50 ++++++++++++++++++------------------- 2 files changed, 27 insertions(+), 36 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 9e74718d2b..0fbceadd9e 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -163,23 +163,14 @@ jobs: - 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} - run: | - bundle install - bundle exec jekyll build -s pages --baseurl "${{ steps.pages.outputs.base_path }}" - # overwrite old files - ls pages/*.md | xargs -II basename I .md | xargs -II rm -rf build/I - rm -rf build/.git build/assets - mv _site/* build/ - name: update docs pages (sphinx) run: | 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" - ./mkversions.py + make BUILDSUBDIR="$docs_dir" dirhtml - uses: actions/upload-artifact@v4 with: name: DocumentationHTML diff --git a/docs/Makefile b/docs/Makefile index dda3aaeb9a..b6acc5f9c0 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,37 +1,37 @@ -## Copyright 2019 United Kingdom Research and Innovation -## Copyright 2019 The University of Manchester -## -## Licensed under the Apache License, Version 2.0 (the "License"); -## you may not use this file except in compliance with the License. -## You may obtain a copy of the License at -## -## http://www.apache.org/licenses/LICENSE-2.0 -## -## Unless required by applicable law or agreed to in writing, software -## distributed under the License is distributed on an "AS IS" BASIS, -## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -## See the License for the specific language governing permissions and -## limitations under the License. -## -## Authors: -## CIL Developers, listed at: https://github.com/TomographicImaging/CIL/blob/master/NOTICE.txt - -# Minimal makefile for Sphinx documentation -# - # You can set these variables from the command line. +JEKYLLOPTS = +JEKYLLBUILD = bundle exec jekyll build +JEKYLLSRCDIR = pages SPHINXOPTS = SPHINXBUILD = sphinx-build SOURCEDIR = source BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". +BUILDSUBDIR = $(shell git rev-parse --abbrev-ref HEAD) help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + @echo extra options + @echo ' web-deps to install website dependencies' + @echo ' web to build website' + @echo ' dirhtml to build docs' + @echo ' serve to serve website & docs' +.PHONY: help Makefile serve web-deps web dirhtml -.PHONY: help Makefile +serve: + @python -m http.server -d "$(BUILDDIR)" +web-deps: + @bundle install +web: + @$(JEKYLLBUILD) -s "$(JEKYLLSRCDIR)" $(JEKYLLOPTS) + @ls "$(JEKYLLSRCDIR)"/*.md | xargs -II basename I .md | xargs -II rm -rf "$(BUILDDIR)/I" + @rm -rf "$(BUILDDIR)/assets" + @mv _site/* "$(BUILDDIR)/" +dirhtml: + @rm -rf "$(BUILDDIR)/$(BUILDSUBDIR)" + @./mkdemos.py + @$(SPHINXBUILD) -b dirhtml $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/$(BUILDSUBDIR)" + @./mkversions.py # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) From 04878d5dbbc5f4706b2b2cfec0ba8573239a3c55 Mon Sep 17 00:00:00 2001 From: Casper da Costa-Luis Date: Wed, 14 Feb 2024 23:07:31 +0000 Subject: [PATCH 09/17] fix nav dropdown links --- docs/pages/_config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/_config.yml b/docs/pages/_config.yml index 383899bad8..fb94eed776 100644 --- a/docs/pages/_config.yml +++ b/docs/pages/_config.yml @@ -1,5 +1,5 @@ # jekyll config -remote_theme: Phlow/feeling-responsive +remote_theme: TomographicImaging/feeling-responsive # TODO: revert after https://github.com/Phlow/feeling-responsive/pull/276 title: CIL slogan: The Core Imaging Library description: | From c6cb2f5d6764f45496f489ebbef4cd2b5b007e62 Mon Sep 17 00:00:00 2001 From: Casper da Costa-Luis Date: Wed, 14 Feb 2024 23:40:37 +0000 Subject: [PATCH 10/17] whitespace --- CITATION.cff | 80 ++++++------- docs/source/developer_guide.rst | 38 +++--- docs/source/index.rst | 198 +++++++++++++++----------------- 3 files changed, 149 insertions(+), 167 deletions(-) diff --git a/CITATION.cff b/CITATION.cff index dc687e0294..b90d2536fe 100644 --- a/CITATION.cff +++ b/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 diff --git a/docs/source/developer_guide.rst b/docs/source/developer_guide.rst index 4568ff7ae2..0e7fcd4df1 100644 --- a/docs/source/developer_guide.rst +++ b/docs/source/developer_guide.rst @@ -1,21 +1,17 @@ -.. Copyright 2020 United Kingdom Research and Innovation - Copyright 2020 The University of Manchester - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - Authors: - CIL Developers, listed at: https://github.com/TomographicImaging/CIL/blob/master/NOTICE.txt - Kyle Pidgeon (UKRI-STFC) +.. Copyright 2020 United Kingdom Research and Innovation + Copyright 2020 The University of Manchester + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + Authors: + CIL Developers, listed at: https://github.com/TomographicImaging/CIL/blob/master/NOTICE.txt + Kyle Pidgeon (UKRI-STFC) Developers' Guide ***************** @@ -140,18 +136,14 @@ Make sure that each contributed file contains the following text enclosed in the :: -..Copyright 2022 United Kingdom Research and Innovation + Copyright 2022 United Kingdom Research and Innovation Copyright 2022 The University of Manchester Copyright [yyyy] [name of copyright owner] - Author(s): [Author name, Author email (optional)] - Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - http://www.apache.org/licenses/LICENSE-2.0 - Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. diff --git a/docs/source/index.rst b/docs/source/index.rst index 99d2968e09..5c6aac4d7b 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,104 +1,94 @@ -.. Copyright 2019 United Kingdom Research and Innovation - Copyright 2019 The University of Manchester - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - Authors: - CIL Developers, listed at: https://github.com/TomographicImaging/CIL/blob/master/NOTICE.txt - - -.. CCPi-Framework documentation master file, created by - sphinx-quickstart on Tue Mar 19 15:12:44 2019. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to CIL's documentation! -############################### - -The aim of this package is to enable rapid prototyping of optimisation-based -reconstruction problems, i.e. defining and solving different optimization problems to enforce different properties on the reconstructed image, while being -powerful enough to be employed on real scale problems. - -Firstly, it provides a framework to handle acquisition and reconstruction -data and metadata; it also provides a basic input/output package to read data -from different sources, e.g. Nikon X-Radia, NeXus. - -Secondly, it provides an object-oriented framework for defining mathematical -operators and functions as well a collection of useful example operators and -functions. Both smooth and non-smooth functions can be used. - -Further, it provides a number of high-level generic implementations of -optimisation algorithms to solve generically formulated optimisation problems -constructed from operator and function objects. - -Demos and Examples -================== -A number of demos can be found in the `CIL-Demos`_ repository. - -For detailed information refer to our articles and the repositories -with the code to reproduce the article's results. - -1. Jørgensen JS et al. 2021 Core Imaging Library Part I: a versatile python framework for tomographic imaging -https://doi.org/10.1098/rsta.2020.0192 . Phil. Trans. R. Soc. A 20200192. -The code to reproduce the article results. https://github.com/TomographicImaging/Paper-2021-RSTA-CIL-Part-I - -2. Papoutsellis E et al. 2021 Core Imaging Library - Part II: multichannel reconstruction for dynamic and spectral -tomography https://doi.org/10.1098/rsta.2020.0193 Phil. Trans. R. Soc. A 20200193. -The code to reproduce the article results. https://github.com/TomographicImaging/Paper-2021-RSTA-CIL-Part-II - - -Cite this work -============== - -If you use this software please consider citing one or both of the articles above. - -Software documentation Index -**************************** - -.. toctree:: - :maxdepth: 3 - :caption: Contents: - :name: mastertoc - - introduction - framework - io - optimisation - processors - recon - utilities - plugins - developer_guide - demos - -.. Indices and tables -.. ================== - -.. * :ref:`genindex` -.. * :ref:`modindex` -.. * :ref:`search` - -Contacts -======== - -Please refer to the main `CCPi website`_ for up-to-date information. - -The CCPi developers may be contacted: - -* by joining the `devel mailing list`_ -* on the CIL's GitHub repository page https://github.com/TomographicImaging/CIL.git or -* on the CIL Discord channel https://discord.gg/9NTWu9MEGq - -.. _devel mailing list: https://www.jiscmail.ac.uk/cgi-bin/webadmin?A0=CCPI-DEVEL -.. _CCPi website: https://www.ccpi.ac.uk -.. _CIL-Demos: https://github.com/vais-ral/CIL-Demos +.. Copyright 2019 United Kingdom Research and Innovation + Copyright 2019 The University of Manchester + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + Authors: + CIL Developers, listed at: https://github.com/TomographicImaging/CIL/blob/master/NOTICE.txt + +Welcome to CIL's documentation! +############################### + +The aim of this package is to enable rapid prototyping of optimisation-based +reconstruction problems, i.e. defining and solving different optimization problems to enforce different properties on the reconstructed image, while being +powerful enough to be employed on real scale problems. + +Firstly, it provides a framework to handle acquisition and reconstruction +data and metadata; it also provides a basic input/output package to read data +from different sources, e.g. Nikon X-Radia, NeXus. + +Secondly, it provides an object-oriented framework for defining mathematical +operators and functions as well a collection of useful example operators and +functions. Both smooth and non-smooth functions can be used. + +Further, it provides a number of high-level generic implementations of +optimisation algorithms to solve generically formulated optimisation problems +constructed from operator and function objects. + +Demos and Examples +================== +A number of demos can be found in the `CIL-Demos`_ repository. + +For detailed information refer to our articles and the repositories +with the code to reproduce the article's results. + +1. Jørgensen JS et al. 2021 Core Imaging Library Part I: a versatile python framework for tomographic imaging +https://doi.org/10.1098/rsta.2020.0192 . Phil. Trans. R. Soc. A 20200192. +The code to reproduce the article results. https://github.com/TomographicImaging/Paper-2021-RSTA-CIL-Part-I + +2. Papoutsellis E et al. 2021 Core Imaging Library - Part II: multichannel reconstruction for dynamic and spectral +tomography https://doi.org/10.1098/rsta.2020.0193 Phil. Trans. R. Soc. A 20200193. +The code to reproduce the article results. https://github.com/TomographicImaging/Paper-2021-RSTA-CIL-Part-II + + +Cite this work +============== + +If you use this software please consider citing one or both of the articles above. + +Software documentation Index +**************************** + +.. toctree:: + :maxdepth: 3 + :caption: Contents: + :name: mastertoc + + introduction + framework + io + optimisation + processors + recon + utilities + plugins + developer_guide + demos + +.. Indices and tables +.. ================== + +.. * :ref:`genindex` +.. * :ref:`modindex` +.. * :ref:`search` + +Contacts +======== + +Please refer to the main `CCPi website`_ for up-to-date information. + +The CCPi developers may be contacted: + +* by joining the `devel mailing list`_ +* on the CIL's GitHub repository page https://github.com/TomographicImaging/CIL.git or +* on the CIL Discord channel https://discord.gg/9NTWu9MEGq + +.. _devel mailing list: https://www.jiscmail.ac.uk/cgi-bin/webadmin?A0=CCPI-DEVEL +.. _CCPi website: https://www.ccpi.ac.uk +.. _CIL-Demos: https://github.com/vais-ral/CIL-Demos From e50911a0eea05edc431b04c6cd49b9a399b3544d Mon Sep 17 00:00:00 2001 From: Casper da Costa-Luis Date: Wed, 14 Feb 2024 23:41:54 +0000 Subject: [PATCH 11/17] drop .git suffix --- README.md | 2 +- docs/source/developer_guide.rst | 2 +- docs/source/index.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 5d2eef04f3..f371adf843 100644 --- a/README.md +++ b/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 diff --git a/docs/source/developer_guide.rst b/docs/source/developer_guide.rst index 0e7fcd4df1..6a8eae88b4 100644 --- a/docs/source/developer_guide.rst +++ b/docs/source/developer_guide.rst @@ -106,7 +106,7 @@ a HTTP server to view the documentation. Example: :: - git clone --recurse-submodule git@github.com:TomographicImaging/CIL.git + git clone --recurse-submodule git@github.com:TomographicImaging/CIL cd CIL sh scripts/create_local_env_for_cil_development_tests.sh -n NUMPY_VERSION -p PYTHON_VERSION -e ENVIRONMENT_NAME conda activate ENVIRONMENT_NAME diff --git a/docs/source/index.rst b/docs/source/index.rst index 5c6aac4d7b..99ceeb8164 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -86,7 +86,7 @@ Please refer to the main `CCPi website`_ for up-to-date information. The CCPi developers may be contacted: * by joining the `devel mailing list`_ -* on the CIL's GitHub repository page https://github.com/TomographicImaging/CIL.git or +* on the CIL's GitHub repository page https://github.com/TomographicImaging/CIL or * on the CIL Discord channel https://discord.gg/9NTWu9MEGq .. _devel mailing list: https://www.jiscmail.ac.uk/cgi-bin/webadmin?A0=CCPI-DEVEL From 0e41eba138d9bb69d4a5d1476b6420bdeba6d3cd Mon Sep 17 00:00:00 2001 From: Casper da Costa-Luis Date: Wed, 14 Feb 2024 23:42:14 +0000 Subject: [PATCH 12/17] fix docs landing titles --- docs/source/index.rst | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 99ceeb8164..a8cd5bf00d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -38,6 +38,11 @@ A number of demos can be found in the `CIL-Demos`_ repository. For detailed information refer to our articles and the repositories with the code to reproduce the article's results. +Cite this work +============== + +If you use this software please consider citing one or both of the articles below. + 1. Jørgensen JS et al. 2021 Core Imaging Library Part I: a versatile python framework for tomographic imaging https://doi.org/10.1098/rsta.2020.0192 . Phil. Trans. R. Soc. A 20200192. The code to reproduce the article results. https://github.com/TomographicImaging/Paper-2021-RSTA-CIL-Part-I @@ -46,18 +51,11 @@ The code to reproduce the article results. https://github.com/TomographicImaging tomography https://doi.org/10.1098/rsta.2020.0193 Phil. Trans. R. Soc. A 20200193. The code to reproduce the article results. https://github.com/TomographicImaging/Paper-2021-RSTA-CIL-Part-II - -Cite this work -============== - -If you use this software please consider citing one or both of the articles above. - -Software documentation Index -**************************** +Table of Contents +================= .. toctree:: :maxdepth: 3 - :caption: Contents: :name: mastertoc introduction From 819e2ffb96a00ed4a181cd4227d17f3db257bf01 Mon Sep 17 00:00:00 2001 From: Casper da Costa-Luis Date: Thu, 29 Feb 2024 15:19:05 +0000 Subject: [PATCH 13/17] docs: make dirhtml --- docs/source/developer_guide.rst | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/docs/source/developer_guide.rst b/docs/source/developer_guide.rst index 6a8eae88b4..87db5acd27 100644 --- a/docs/source/developer_guide.rst +++ b/docs/source/developer_guide.rst @@ -98,10 +98,9 @@ a HTTP server to view the documentation. #. Update conda with ``conda update -n base -c defaults conda`` #. Follow the instructions `here `_ to create a conda environment and build ``cil`` from source #. Go to ``docs`` folder -#. Install packages from ``docs/docs_environment.yml`` (with 'name' changed to ENVIRONMENT_NAME) using ``conda env update -f docs_environment.yml`` -#. Download the notebooks for rendering in the documentation with ``python mkdemos.py`` -#. Build the documentation ``sphinx-build -b dirhtml source build`` -#. Start a HTTP server to serve documentation with ``python -m http.server --directory build`` +#. Install packages from ``docs/docs_environment.yml`` +#. Build the documentation with ``make dirhtml`` +#. Start an HTTP server with ``make serve`` to access the docs via `localhost:8000 `_. Example: :: @@ -115,14 +114,12 @@ Example: cd docs conda update -n base -c defaults conda conda env update -f docs_environment.yml # with the name field set to ENVIRONMENT_NAME - python mkdemos.py - sphinx-build -b dirhtml source build - python -m http.server -d build + make dirhtml serve Notebooks gallery ----------------- -The ``mkdemos.py`` script: +The ``mkdemos.py`` script (called by ``make dirhtml``): - downloads notebooks from external URLs to ``source/demos/*.ipynb`` - uses the ``demos-template.rst`` file to generate the gallery in ``source/demos.rst`` @@ -136,8 +133,8 @@ Make sure that each contributed file contains the following text enclosed in the :: - Copyright 2022 United Kingdom Research and Innovation - Copyright 2022 The University of Manchester + Copyright [yyyy] United Kingdom Research and Innovation + Copyright [yyyy] The University of Manchester Copyright [yyyy] [name of copyright owner] Author(s): [Author name, Author email (optional)] Licensed under the Apache License, Version 2.0 (the "License"); From 84357d3d7090f4ff5f2cacb6c8dcde73b94ba508 Mon Sep 17 00:00:00 2001 From: Casper da Costa-Luis Date: Fri, 12 Apr 2024 15:35:35 +0100 Subject: [PATCH 14/17] remove duplicate entries & sanitise format --- docs/source/refs.bib | 294 +++++++++++++------------------------------ 1 file changed, 85 insertions(+), 209 deletions(-) diff --git a/docs/source/refs.bib b/docs/source/refs.bib index 26c2e9f2cc..4ca6c4e543 100644 --- a/docs/source/refs.bib +++ b/docs/source/refs.bib @@ -1,46 +1,19 @@ -.. Copyright 2021 United Kingdom Research and Innovation - Copyright 2021 The University of Manchester - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - Authors: - CIL Developers, listed at: https://github.com/TomographicImaging/CIL/blob/master/NOTICE.txt - - - @article{guler1992new, - title={New proximal point algorithms for convex minimization}, - author={G{\"u}ler, Osman}, - journal={SIAM Journal on Optimization}, - volume={2}, - number={4}, - pages={649--664}, - year={1992}, - publisher={SIAM} -} - - +title={New proximal point algorithms for convex minimization}, +author={G{\"u}ler, Osman}, +journal={SIAM Journal on Optimization}, +volume={2}, +number={4}, +pages={649--664}, +year={1992}, +publisher={SIAM}} @book{nesterov2003introductory, - title={Introductory lectures on convex optimization: A basic course}, - author={Nesterov, Yurii}, - volume={87}, - year={2003}, - publisher={Springer Science \& Business Media} -} - - - -@Article{CP2011, +title={Introductory lectures on convex optimization: A basic course}, +author={Nesterov, Yurii}, +volume={87}, +year={2003}, +publisher={Springer Science \& Business Media}} +@article{CP2011, author={Chambolle, Antonin and Pock, Thomas}, title={A First-Order Primal-Dual Algorithm for Convex Problems with Applications to Imaging}, @@ -51,110 +24,64 @@ @Article{CP2011 volume={40}, number={1}, pages={120-145}, -abstract={In this paper we study a first-order primal-dual algorithm for non-smooth convex optimization problems with known saddle-point structure. We prove convergence to a saddle-point with rate O(1/N) in finite dimensions for the complete class of problems. We further show accelerations of the proposed algorithm to yield improved rates on problems with some degree of smoothness. In particular we show that we can achieve O(1/N2) convergence on problems, where the primal or the dual objective is uniformly convex, and we can show linear convergence, i.e. O($\omega$N) for some $\omega$∈(0,1), on smooth problems. The wide applicability of the proposed algorithm is demonstrated on several imaging problems such as image denoising, image deconvolution, image inpainting, motion estimation and multi-label image segmentation.}, issn={1573-7683}, doi={10.1007/s10851-010-0251-1}, -url={https://doi.org/10.1007/s10851-010-0251-1} -} - - +url={https://doi.org/10.1007/s10851-010-0251-1}} @article{EZXC2010, -author = {Esser, Ernie and Zhang, Xiaoqun and Chan, Tony F.}, -title = {A General Framework for a Class of First Order Primal-Dual Algorithms for Convex Optimization in Imaging Science}, -journal = {SIAM Journal on Imaging Sciences}, -volume = {3}, -number = {4}, -pages = {1015-1046}, -year = {2010}, -doi = {10.1137/09076934X}, - -URL = { - https://doi.org/10.1137/09076934X - -}, -eprint = { - https://doi.org/10.1137/09076934X - -} - -} - - - +author={Esser, Ernie and Zhang, Xiaoqun and Chan, Tony F.}, +title={A General Framework for a Class of First Order Primal-Dual Algorithms for Convex Optimization in Imaging Science}, +journal={SIAM Journal on Imaging Sciences}, +volume={3}, +number={4}, +pages={1015-1046}, +year={2010}, +doi={10.1137/09076934X}, +URL={https://doi.org/10.1137/09076934X}, +eprint={https://doi.org/10.1137/09076934X}} @article{Papoutsellis_et_al_2021, -author = {Papoutsellis, Evangelos and Ametova, Evelina and Delplancke, Claire and Fardell, Gemma and J\"{o}rgensen, Jakob S. and Pasca, Edoardo and Turner, Martin and Warr, Ryan and Lionheart, William R. B. and Withers, Philip J. }, -title = {Core Imaging Library - Part II: multichannel reconstruction for dynamic and spectral tomography}, -journal = {Philosophical Transactions of the Royal Society A: Mathematical, Physical and Engineering Sciences}, -volume = {379}, -number = {2204}, -pages = {20200193}, -year = {2021}, -doi = {10.1098/rsta.2020.0193}, - -URL = {https://royalsocietypublishing.org/doi/abs/10.1098/rsta.2020.0193}, -eprint = {https://royalsocietypublishing.org/doi/pdf/10.1098/rsta.2020.0193} -, - abstract = { The newly developed core imaging library (CIL) is a flexible plug and play library for tomographic imaging with a specific focus on iterative reconstruction. CIL provides building blocks for tailored regularized reconstruction algorithms and explicitly supports multichannel tomographic data. In the first part of this two-part publication, we introduced the fundamentals of CIL. This paper focuses on applications of CIL for multichannel data, e.g. dynamic and spectral. We formalize different optimization problems for colour processing, dynamic and hyperspectral tomography and demonstrate CIL’s capabilities for designing state-of-the-art reconstruction methods through case studies and code snapshots. This article is part of the theme issue β€˜Synergistic tomographic image reconstruction: part 2’. } -} - - - - - +author={Papoutsellis, Evangelos and Ametova, Evelina and Delplancke, Claire and Fardell, Gemma and J\"{o}rgensen, Jakob S. and Pasca, Edoardo and Turner, Martin and Warr, Ryan and Lionheart, William R. B. and Withers, Philip J. }, +title={Core Imaging Library - Part II: multichannel reconstruction for dynamic and spectral tomography}, +journal={Philosophical Transactions of the Royal Society A: Mathematical, Physical and Engineering Sciences}, +volume={379}, +number={2204}, +pages={20200193}, +year={2021}, +doi={10.1098/rsta.2020.0193}, +URL={https://royalsocietypublishing.org/doi/abs/10.1098/rsta.2020.0193}, +eprint={https://royalsocietypublishing.org/doi/pdf/10.1098/rsta.2020.0193}} @article{Jorgensen_et_al_2021, -author = {J\"{o}rgensen, J. S. and Ametova, E. and Burca, G. and Fardell, G. and Papoutsellis, E. and Pasca, E. and Thielemans, K. and Turner, M. and Warr, R. and Lionheart, W. R. B. and Withers, P. J. }, -title = {Core Imaging Library - Part I: a versatile Python framework for tomographic imaging}, -journal = {Philosophical Transactions of the Royal Society A: Mathematical, Physical and Engineering Sciences}, -volume = {379}, -number = {2204}, -pages = {20200192}, -year = {2021}, -doi = {10.1098/rsta.2020.0192}, - -URL = {https://royalsocietypublishing.org/doi/abs/10.1098/rsta.2020.0192}, -eprint = {https://royalsocietypublishing.org/doi/pdf/10.1098/rsta.2020.0192} -, - abstract = { We present the Core Imaging Library (CIL), an open-source Python framework for tomographic imaging with particular emphasis on reconstruction of challenging datasets. Conventional filtered back-projection reconstruction tends to be insufficient for highly noisy, incomplete, non-standard or multi-channel data arising for example in dynamic, spectral and in situ tomography. CIL provides an extensive modular optimization framework for prototyping reconstruction methods including sparsity and total variation regularization, as well as tools for loading, preprocessing and visualizing tomographic data. The capabilities of CIL are demonstrated on a synchrotron example dataset and three challenging cases spanning golden-ratio neutron tomography, cone-beam X-ray laminography and positron emission tomography. This article is part of the theme issue β€˜Synergistic tomographic image reconstruction: part 2’. } -} - - -@ARTICLE{BeckTeboulle_a, - author={Beck, Amir and Teboulle, Marc}, - journal={IEEE Transactions on Image Processing}, - title={Fast Gradient-Based Algorithms for Constrained Total Variation Image Denoising and Deblurring Problems}, - year={2009}, - volume={18}, - number={11}, - pages={2419-2434}, - doi={10.1109/TIP.2009.2028250}} - - +author={J\"{o}rgensen, J. S. and Ametova, E. and Burca, G. and Fardell, G. and Papoutsellis, E. and Pasca, E. and Thielemans, K. and Turner, M. and Warr, R. and Lionheart, W. R. B. and Withers, P. J. }, +title={Core Imaging Library - Part I: a versatile Python framework for tomographic imaging}, +journal={Philosophical Transactions of the Royal Society A: Mathematical, Physical and Engineering Sciences}, +volume={379}, +number={2204}, +pages={20200192}, +year={2021}, +doi={10.1098/rsta.2020.0192}, +URL={https://royalsocietypublishing.org/doi/abs/10.1098/rsta.2020.0192}, +eprint={https://royalsocietypublishing.org/doi/pdf/10.1098/rsta.2020.0192}} +@article{BeckTeboulle_a, +author={Beck, Amir and Teboulle, Marc}, +journal={IEEE Transactions on Image Processing}, +title={Fast Gradient-Based Algorithms for Constrained Total Variation Image Denoising and Deblurring Problems}, +year={2009}, +volume={18}, +number={11}, +pages={2419-2434}, +doi={10.1109/TIP.2009.2028250}} @article{BeckTeboulle_b, -author = {Beck, Amir and Teboulle, Marc}, -title = {A Fast Iterative Shrinkage-Thresholding Algorithm for Linear Inverse Problems}, -journal = {SIAM Journal on Imaging Sciences}, -volume = {2}, -number = {1}, -pages = {183-202}, -year = {2009}, -doi = {10.1137/080716542}, - -URL = { - https://doi.org/10.1137/080716542 - -}, -eprint = { - https://doi.org/10.1137/080716542 - -} -, - abstract = { We consider the class of iterative shrinkage-thresholding algorithms (ISTA) for solving linear inverse problems arising in signal/image processing. This class of methods, which can be viewed as an extension of the classical gradient algorithm, is attractive due to its simplicity and thus is adequate for solving large-scale problems even with dense matrix data. However, such methods are also known to converge quite slowly. In this paper we present a new fast iterative shrinkage-thresholding algorithm (FISTA) which preserves the computational simplicity of ISTA but with a global rate of convergence which is proven to be significantly better, both theoretically and practically. Initial promising numerical results for wavelet-based image deblurring demonstrate the capabilities of FISTA which is shown to be faster than ISTA by several orders of magnitude. } -} - - -@Article{Rasch2020, -author={Rasch, Julian -and Chambolle, Antonin}, +author={Beck, Amir and Teboulle, Marc}, +title={A Fast Iterative Shrinkage-Thresholding Algorithm for Linear Inverse Problems}, +journal={SIAM Journal on Imaging Sciences}, +volume={2}, +number={1}, +pages={183-202}, +year={2009}, +doi={10.1137/080716542}, +URL={https://doi.org/10.1137/080716542}, +eprint={https://doi.org/10.1137/080716542}} +@article{Rasch2020, +author={Rasch, Julian and Chambolle, Antonin}, title={Inexact first-order primal--dual algorithms}, journal={Computational Optimization and Applications}, year={2020}, @@ -163,21 +90,18 @@ @Article{Rasch2020 volume={76}, number={2}, pages={381-430}, -abstract={We investigate the convergence of a recently popular class of first-order primal--dual algorithms for saddle point problems under the presence of errors in the proximal maps and gradients. We study several types of errors and show that, provided a sufficient decay of these errors, the same convergence rates as for the error-free algorithm can be established. More precisely, we prove the (optimal) {\$}{\$}O{\backslash}left( 1/N{\backslash}right){\$}{\$} convergence to a saddle point in finite dimensions for the class of non-smooth problems considered in this paper, and prove a {\$}{\$}O{\backslash}left( 1/N^2{\backslash}right){\$}{\$} or even linear {\$}{\$}O{\backslash}left( {\backslash}theta ^N{\backslash}right){\$}{\$} convergence rate if either the primal or dual objective respectively both are strongly convex. Moreover we show that also under a slower decay of errors we can establish rates, however slower and directly depending on the decay of the errors. We demonstrate the performance and practical use of the algorithms on the example of nested algorithms and show how they can be used to split the global objective more efficiently.}, issn={1573-2894}, doi={10.1007/s10589-020-00186-y}, url={https://doi.org/10.1007/s10589-020-00186-y}} - @book{Kak2001, - doi = {10.1137/1.9780898719277}, - url = {https://doi.org/10.1137/1.9780898719277}, - year = {2001}, - month = jan, - publisher = {Society for Industrial and Applied Mathematics}, - author = {Avinash C. Kak and Malcolm Slaney}, - title = {Principles of Computerized Tomographic Imaging}} - -@Article{Zhu2010, +doi={10.1137/1.9780898719277}, +url={https://doi.org/10.1137/1.9780898719277}, +year={2001}, +month=jan, +publisher={Society for Industrial and Applied Mathematics}, +author={Avinash C. Kak and Malcolm Slaney}, +title={Principles of Computerized Tomographic Imaging}} +@article{Zhu2010, author={Zhu, Mingqiang and Wright, Stephen J. and Chan, Tony F.}, @@ -189,65 +113,17 @@ @Article{Zhu2010 volume={47}, number={3}, pages={377-400}, -abstract={Image restoration models based on total variation (TV) have become popular since their introduction by Rudin, Osher, and Fatemi (ROF) in 1992. The dual formulation of this model has a quadratic objective with separable constraints, making projections onto the feasible set easy to compute. This paper proposes application of gradient projection (GP) algorithms to the dual formulation. We test variants of GP with different step length selection and line search strategies, including techniques based on the Barzilai-Borwein method. Global convergence can in some cases be proved by appealing to existing theory. We also propose a sequential quadratic programming (SQP) approach that takes account of the curvature of the boundary of the dual feasible set. Computational experiments show that the proposed approaches perform well in a wide range of applications and that some are significantly faster than previously proposed methods, particularly when only modest accuracy in the solution is required.}, issn={1573-2894}, doi={10.1007/s10589-008-9225-2}, -url={https://doi.org/10.1007/s10589-008-9225-2} -} - -@ARTICLE{BeckTeboulle_a, - author={Beck, Amir and Teboulle, Marc}, - journal={IEEE Transactions on Image Processing}, - title={Fast Gradient-Based Algorithms for Constrained Total Variation Image Denoising and Deblurring Problems}, - year={2009}, - volume={18}, - number={11}, - pages={2419-2434}, - doi={10.1109/TIP.2009.2028250}} - - -@article{BeckTeboulle_b, -author = {Beck, Amir and Teboulle, Marc}, -title = {A Fast Iterative Shrinkage-Thresholding Algorithm for Linear Inverse Problems}, -journal = {SIAM Journal on Imaging Sciences}, -volume = {2}, -number = {1}, -pages = {183-202}, -year = {2009}, -doi = {10.1137/080716542}, - -URL = { - https://doi.org/10.1137/080716542 - -}, -eprint = { - https://doi.org/10.1137/080716542 - -} -, - abstract = { We consider the class of iterative shrinkage-thresholding algorithms (ISTA) for solving linear inverse problems arising in signal/image processing. This class of methods, which can be viewed as an extension of the classical gradient algorithm, is attractive due to its simplicity and thus is adequate for solving large-scale problems even with dense matrix data. However, such methods are also known to converge quite slowly. In this paper we present a new fast iterative shrinkage-thresholding algorithm (FISTA) which preserves the computational simplicity of ISTA but with a global rate of convergence which is proven to be significantly better, both theoretically and practically. Initial promising numerical results for wavelet-based image deblurring demonstrate the capabilities of FISTA which is shown to be faster than ISTA by several orders of magnitude. } -} - - - +url={https://doi.org/10.1007/s10589-008-9225-2}} @article{CombettesValerie, -author = {Combettes, Patrick L. and Wajs, Val\'erie R.}, -title = {Signal Recovery by Proximal Forward-Backward Splitting}, -journal = {Multiscale Modeling \& Simulation}, -volume = {4}, -number = {4}, -pages = {1168-1200}, -year = {2005}, -doi = {10.1137/050626090}, - -URL = { - https://doi.org/10.1137/050626090 - -}, -eprint = { - https://doi.org/10.1137/050626090 - -} -, - abstract = { We show that various inverse problems in signal recovery can be formulated as the generic problem of minimizing the sum of two convex functions with certain regularity properties. This formulation makes it possible to derive existence, uniqueness, characterization, and stability results in a unified and standardized fashion for a large class of apparently disparate problems. Recent results on monotone operator splitting methods are applied to establish the convergence of a forward-backward algorithm to solve the generic problem. In turn, we recover, extend, and provide a simplified analysis for a variety of existing iterative methods. Applications to geometry/texture image decomposition schemes are also discussed. A novelty of our framework is to use extensively the notion of a proximity operator, which was introduced by Moreau in the 1960s. } -} +author={Combettes, Patrick L. and Wajs, Val\'erie R.}, +title={Signal Recovery by Proximal Forward-Backward Splitting}, +journal={Multiscale Modeling \& Simulation}, +volume={4}, +number={4}, +pages={1168-1200}, +year={2005}, +doi={10.1137/050626090}, +URL={https://doi.org/10.1137/050626090}, +eprint={https://doi.org/10.1137/050626090}} From 15b71af0d0f9e41e5512e7648075484fb9ff97a0 Mon Sep 17 00:00:00 2001 From: Casper da Costa-Luis Date: Thu, 25 Apr 2024 10:45:44 +0100 Subject: [PATCH 15/17] update cross-refs --- .github/workflows/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/README.md b/.github/workflows/README.md index 35f6f00bc9..ea6de52ea9 100644 --- a/.github/workflows/README.md +++ b/.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,11 +38,11 @@ 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` - uploads a `DocumentationHTML` artifact (which can be downloaded to view locally for debugging) From 49c4293e5586449b9356af5940c140c229be4225 Mon Sep 17 00:00:00 2001 From: Casper da Costa-Luis Date: Thu, 25 Apr 2024 10:46:38 +0100 Subject: [PATCH 16/17] local (ruby) dev instructions --- .github/workflows/README.md | 19 +++++++++++++++---- docs/Gemfile.lock | 2 +- docs/Makefile | 1 + docs/source/developer_guide.rst | 13 +++++++++---- 4 files changed, 26 insertions(+), 9 deletions(-) diff --git a/.github/workflows/README.md b/.github/workflows/README.md index ea6de52ea9..cf395ad959 100644 --- a/.github/workflows/README.md +++ b/.github/workflows/README.md @@ -44,12 +44,23 @@ The [docs](./build.yml#L124) job: - 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 to view the documentation. diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index 23687f55ad..58b06d6248 100644 --- a/docs/Gemfile.lock +++ b/docs/Gemfile.lock @@ -127,4 +127,4 @@ DEPENDENCIES jekyll-remote-theme BUNDLED WITH - 2.5.6 + 2.5.9 diff --git a/docs/Makefile b/docs/Makefile index b6acc5f9c0..b32307a2f0 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -19,6 +19,7 @@ help: serve: @python -m http.server -d "$(BUILDDIR)" web-deps: + @gem install bundler @bundle install web: @$(JEKYLLBUILD) -s "$(JEKYLLSRCDIR)" $(JEKYLLOPTS) diff --git a/docs/source/developer_guide.rst b/docs/source/developer_guide.rst index 87db5acd27..eb434d86b9 100644 --- a/docs/source/developer_guide.rst +++ b/docs/source/developer_guide.rst @@ -88,7 +88,9 @@ Rendered Building documentation locally ------------------------------ -The easiest way to test changes to documentation is to build the docs locally. To do this, you will need a working ``cil`` installation. +The easiest way to test documentation changes is to open a pull request and `download the rendered documentation from the CI `_. + +Alternatively, to build the docs locally, you will need a working ``cil`` installation. For development of the documentation embedded within the source code itself (e.g. docstrings), you should build ``cil`` from source. The following steps can be used to create an environment that is suitable for building ``cil`` and its documentation, and to start @@ -98,8 +100,10 @@ a HTTP server to view the documentation. #. Update conda with ``conda update -n base -c defaults conda`` #. Follow the instructions `here `_ to create a conda environment and build ``cil`` from source #. Go to ``docs`` folder -#. Install packages from ``docs/docs_environment.yml`` -#. Build the documentation with ``make dirhtml`` +#. Install packages from ``docs_environment.yml`` +#. [Install Ruby version 3.2](https://www.ruby-lang.org/en/documentation/installation/#installers) +#. Install the web dependencies with ``make web-deps`` +#. Build the documentation with ``make dirhtml web`` #. Start an HTTP server with ``make serve`` to access the docs via `localhost:8000 `_. Example: @@ -114,7 +118,8 @@ Example: cd docs conda update -n base -c defaults conda conda env update -f docs_environment.yml # with the name field set to ENVIRONMENT_NAME - make dirhtml serve + make web-deps # install dependencies (requires ruby 3.2) + make dirhtml web serve Notebooks gallery ----------------- From 86ccf55cba1a2af2f21247727bfe20772f4ccb94 Mon Sep 17 00:00:00 2001 From: Casper da Costa-Luis Date: Tue, 30 Apr 2024 15:38:04 +0100 Subject: [PATCH 17/17] CCPi developers => CIL developers --- Wrappers/Python/CMake/setup.py.in | 5 ++--- docs/pages/_config.yml | 2 +- docs/pages/_data/authors.yml | 2 +- docs/source/conf.py | 2 +- docs/source/index.rst | 2 +- 5 files changed, 6 insertions(+), 7 deletions(-) diff --git a/Wrappers/Python/CMake/setup.py.in b/Wrappers/Python/CMake/setup.py.in index 96d7ae0687..d883baf615 100644 --- a/Wrappers/Python/CMake/setup.py.in +++ b/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", diff --git a/docs/pages/_config.yml b/docs/pages/_config.yml index fb94eed776..f8d0106311 100644 --- a/docs/pages/_config.yml +++ b/docs/pages/_config.yml @@ -62,7 +62,7 @@ defaults: show_meta: false # sidebar: # left, right (default undefined means none) comments: false - author: CCPi Developers + author: CIL developers #google_site_verification: '' #bing_webmastertools_id: '' diff --git a/docs/pages/_data/authors.yml b/docs/pages/_data/authors.yml index eb1fd93730..b1d5c7d6e7 100644 --- a/docs/pages/_data/authors.yml +++ b/docs/pages/_data/authors.yml @@ -1,6 +1,6 @@ # https://github.com/Phlow/feeling-responsive/blob/gh-pages/_data/authors.yml # http://blog.sorryapp.com/blogging-with-jekyll/2014/02/06/adding-authors-to-your-jekyll-site.html ccpi-devs: - name: CCPi Developers + name: CIL developers siterole: "webmaster, developer, copywriter, designer" uri: https://github.com/TomographicImaging/CIL/graphs/contributors diff --git a/docs/source/conf.py b/docs/source/conf.py index 4331fad909..e0f348a186 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -29,7 +29,7 @@ # Project information project = 'CIL' copyright = '2017-2024' -author = 'CCPi developers' +author = 'CIL developers' version = version.version release = version _baseurl = f'/{getenv("GITHUB_REPOSITORY", "").split("/", 1)[-1]}/'.replace("//", "/") diff --git a/docs/source/index.rst b/docs/source/index.rst index a8cd5bf00d..7f93157df8 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -81,7 +81,7 @@ Contacts Please refer to the main `CCPi website`_ for up-to-date information. -The CCPi developers may be contacted: +The CIL developers may be contacted: * by joining the `devel mailing list`_ * on the CIL's GitHub repository page https://github.com/TomographicImaging/CIL or