Update dev instructions

.github/workflows/conda_and_docs_build.yml

@@ -0,0 +1,89 @@
+name: conda_and_docs_build
+
+on:
+  release:
+    types: [published]
+  push:
+    branches: [ master ]
+    tags:
+      - '**'
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  conda_build:
+    runs-on: ubuntu-20.04
+    steps:
+    - uses: actions/checkout@v3.1.0
+      with:
+        fetch-depth: 0
+    - name: conda-build
+      uses: paskino/conda-package-publish-action@v2.0.0
+      with:
+        subDir: 'recipe'
+        channels: '-c conda-forge -c intel -c astra-toolbox/label/dev -c cvxgrp -c ccpi  --override-channels'
+        convert_win: false
+        convert_osx: false
+        test_pyver: 3.9
+        test_npver: 1.22
+    - name: Upload artifact of the conda package.
+      uses: actions/upload-artifact@v3.1.1
+      with:
+        name: cil-package
+        path: recipe/linux-64/cil*
+  docs_build:
+    needs: conda_build
+    runs-on: ubuntu-20.04
+    steps:
+    - uses: actions/checkout@v3.1.0
+      with:
+        fetch-depth: 0
+    - name: change directory
+      run: |
+        ls
+    - name: Download artifact of the conda package.
+      uses: actions/download-artifact@v3.0.1
+      with:
+        name: 'cil-package'
+        path: 'conda_package'
+    - uses: conda-incubator/setup-miniconda@v2
+      with:
+        python-version: 3.7
+    - uses: lauramurgatroyd/build-sphinx-action@v0.1.3
+      with:
+        DOCS_PATH: 'docs'
+        CONDA_BUILD_ENV_FILEPATH: 'docs/docs_environment.yml'
+        ARTIFACT_NAME: 'DocumentationHTML'
+        PACKAGE_FOLDER_PATH: 'conda_package'
+        PACKAGE_NAME: 'cil'
+        PACKAGE_CONDA_CHANNELS: 'conda-forge -c intel -c astra-toolbox/label/dev -c cvxgrp -c ccpi'
+        BUILD_SUBDIR_NAME: 'nightly'
+  docs_publish:
+    needs: docs_build
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/master'
+    steps:
+    - name: Download artifact of the html output.
+      uses: actions/download-artifact@v3.0.1
+      with:
+        name: DocumentationHTML
+        path: docs/build
+    - name: Commit documentation changes
+      run: |
+        git clone https://github.com/TomographicImaging/CIL.git --branch gh-pages --single-branch gh-pages
+        cp -r docs/build/* gh-pages/
+        cd gh-pages
+        touch .nojekyll
+        git config --local user.email "action@github.com"
+        git config --local user.name "GitHub Action"
+        git add .
+        git commit -m "Update documentation" -a || true
+        # The above command will fail if no changes were present, so we ignore
+        # that.
+    - name: Push changes
+      uses: ad-m/github-push-action@v0.6.0
+      with:
+        branch: gh-pages
+        directory: gh-pages
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+

CHANGELOG.md

@@ -18,6 +18,7 @@
     - Handle regularisation toolkit CPU only package error message (#2302)
   - Documentation:
     - Render the user showcase notebooks in the documentation (#2189)
+    - Update on build instructions in README and developer guide for all OS
   - Enhancements:
     - Add prefix argument to TIFFStackReader to load a subset of TIFF files in
     a folder (#2239)

README.md

@@ -120,80 +120,7 @@ Jupyter Notebooks usage examples without any local installation are provided in
 
 ## Building CIL from source code
 
-### Getting the code
-
-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
-```
-
-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
-
-```sh
-git submodule update --init --recursive
-```
-
-### Building with `pip`
-
-#### Install Dependencies
-
-To create a conda environment with all the dependencies for building CIL run the following shell script:
-
-```sh
-bash ./scripts/create_local_env_for_cil_development.sh
-```
-
-Or with the CIL build and test dependencies:
-
-```sh
-bash ./scripts/create_local_env_for_cil_development.sh -t
-```
-
-And then install CIL in to this environment using `pip`.
-
-Alternatively, one can use the `scripts/requirements-test.yml` to create a conda environment with all the
-appropriate dependencies, using the following command:
-
-```sh
-conda env create -f ./scripts/requirements-test.yml
-```
-or, on windows:
-```sh
-conda env create -f ./scripts/requirements-test-windows.yml
-```
-
-#### Build CIL
-
-A C++ compiler is required to build the source code. Let's suppose that the user is in the source directory, then the following commands should work:
-
-```sh
-pip install --no-deps .
-```
-
-If not installing inside a conda environment, then the user might need to set the locations of optional libraries:
-
-```sh
-pip install . -Ccmake.define.IPP_ROOT="<path_to_ipp>" -Ccmake.define.OpenMP_ROOT="<path_to_openmp>"
-```
-
-### Building with Docker
-
-In the repository root, simply update submodules and run `docker build`:
-
-```sh
-git submodule update --init --recursive
-docker build . -t ghcr.io/tomographicimaging/cil
-```
-
-### Testing
-
-One installed, CIL functionality can be tested using the following command:
-
-```sh
-export TESTS_FORCE_GPU=1  # optional, makes GPU test failures noisy
-python -m unittest discover -v ./Wrappers/Python/test
-```
+For instructions on how to build CIL from source code, please see our [Developers' Guide](https://tomographicimaging.github.io/CIL/nightly/developer_guide/)
 
 ## Citing CIL
 

docs/source/developer_guide.rst

@@ -17,7 +17,124 @@ Developers' Guide
 *****************
 
 CIL is an Object Orientated software. It has evolved during the years and it currently does not fully adhere to the following conventions. New additions must comply with
-the following.
+the conventions and documentation guidelines described in this section.
+
+Building CIL from source code
+==============================
+
+Getting the code
+^^^^^^^^^^^^^^^^
+
+In case of local development and testing it is useful to be able to build the software directly. 
+You should first clone this repository as:
+
+.. code:: sh
+
+   git clone git@github.com:TomographicImaging/CIL
+
+The parameter ``--depth 1`` can be added to create a shallow clone with a history truncated to the specified number of commits reducing the size of the clone.
+See `git documentation <https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---depthdepth>`_
+
+
+Building with ``pip``
+^^^^^^^^^^^^^^^^^^^^^
+
+Install Dependencies
+""""""""""""""""""
+
+We suggest creating a conda environment with all the dependencies for building CIL using the appropriate command for your operating system:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 65 15
+
+   * - OS
+     - Command
+     - Status
+   * - Linux
+     - ``conda env create -f https://tomography.stfc.ac.uk/scripts/env/cil_development.yml``
+     - Tested
+   * - Windows
+     - ``conda env create -f https://tomography.stfc.ac.uk/scripts/env/cil_development.yml``
+     - Tested
+   * - MacOS (ARM)
+     - ``conda env create -f https://tomography.stfc.ac.uk/scripts/env/cil_development_osx.yml``
+     - Experimental
+
+.. note::
+   Currently only Linux and Windows are tested and supported. The support on MacOS (ARM) is experimental and certain features are not available and not working, such as FFT filtering for FDK.
+
+Build CIL
+""""""""
+
+A C++ compiler is required to build the source code. Let's suppose that the user is in the source directory, then the following commands should work:
+
+
+.. code:: sh
+
+   pip install -e .
+
+.. note::
+   You need to have a **working compiler** on your system, such as Visual Studio on Windows, GCC on Linux and XCode on MacOS.
+
+
+If not installing inside a conda environment, then the user might need to set the locations of optional libraries:
+
+.. code:: sh
+
+   pip install -e . -Ccmake.define.IPP_ROOT="<path_to_ipp>" -Ccmake.define.OpenMP_ROOT="<path_to_openmp>" -Ccmake.define.CMAKE_BUILD_TYPE=RelWithDebInfo
+
+
+Notes for Windows users
+"""""""""""""""""""""""
+
+One option for development on Windows is using `Windows Subsystem for Linux (WSL) <https://learn.microsoft.com/en-us/windows/wsl/install#change-the-default-linux-distribution-installed>`_
+Launch WSL and install build-essential using:
+
+.. code:: sh
+
+   apt install build-essential
+
+This will enable you to then follow the linux instructions for creating the environment and building CIL.
+
+
+To build for windows you can install Visual Studio Community (or higher) and select the **Desktop development with C++** workload.
+
+If you are developing on Windows with conda, you need to have access to both the Visual Studio compiler and have created the conda environment using the command for Windows above. 
+
+You can achieve this in two ways:
+
+1. by opening a "Developer Command Prompt for Visual Studio" and activating the conda environment from there. This requires you 
+   to know the path to the ``conda.bat`` file, which is typically located in the ``condabin`` subdirectory of your conda installation. 
+   Once located you need to run ``<path_to>\conda.bat activate <env_name>`` to activate the conda environment, and then you can run the build command from there.
+2. by opening the conda prompt and running the ``vcvarsall.bat x64`` file from the Visual Studio installation (with ``x64`` argument), and then running the build command.
+   This requires you to know the path to the ``vcvarsall.bat`` file, 
+   which is typically located in the ``VC/Auxiliary/Build`` subdirectory of your Visual Studio installation.
+
+Note: we tested these instructions with Visual Studio 2026 version 18.1.1
+
+
+Building with Docker
+^^^^^^^^^^^^^^^^^^^^^
+
+In the repository root, simply update submodules and run ``docker build``:
+
+.. code:: sh
+
+   git submodule update --init --recursive
+   docker build . -t ghcr.io/tomographicimaging/cil
+
+
+Testing
+^^^^^^^
+
+Once installed, CIL functionality can be tested using the following command:
+
+.. code:: sh
+
+   export TESTS_FORCE_GPU=1  # optional, makes GPU test failures noisy
+   python -m unittest discover -v ./Wrappers/Python/test
+
 
 Conventions on new CIL objects
 ==============================
@@ -110,6 +227,7 @@ Rendered
 .. automethod:: cil.recon.FBP.FBP.run
 
 
+
 Building documentation locally
 ------------------------------
 
@@ -133,11 +251,11 @@ a HTTP server to view the documentation.
 
 Example:
 ::
-  git clone --recurse-submodule git@github.com:TomographicImaging/CIL
+  git clone 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 env create -f https://tomography.stfc.ac.uk/scripts/env/cil_development.yml
   conda activate ENVIRONMENT_NAME
-  pip install .
+  pip install -e .
   cd docs
   conda update -n base -c defaults conda
   conda env update -f docs_environment.yml # with the name field set to ENVIRONMENT_NAME

recipe/build.sh

@@ -6,7 +6,7 @@ if test $(python -c "from __future__ import print_function; import platform; pri
   echo "Darwin"
   extra_args="$extra_args -DOPENMP_LIBRARIES=${CONDA_PREFIX}/lib -DOPENMP_INCLUDES=${CONDA_PREFIX}/include"
 else
-  echo "something else"
+  echo "Not Darwin"
 fi
 
 export SETUPTOOLS_SCM_PRETEND_VERSION_FOR_CIL="${PKG_VERSION}"