Readthedocs gh actions and iwrap plugins integration

.gitattributes

@@ -1 +1 @@
-iwrap/_version.py export-subst
+

.github/workflows/publish.yml

@@ -0,0 +1,72 @@
+name: build-wheel-and-publish-test-pypi
+
+on:
+  push:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-22.04
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0 
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.x"
+    - name: Install pypa/build
+      run: >-
+        python3 -m pip install pip setuptools wheel build
+    - name: Build a binary wheel and a source tarball
+      run: python3 -m build .
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+
+  publish-to-pypi:
+    name: Publish iWrap distribution to PyPI
+    if: startsWith(github.ref, 'refs/tags/')  # only publish to PyPI on tag pushes
+    needs:
+    - build
+    runs-on: ubuntu-22.04
+    environment:
+      name: pypi
+      url: https://pypi.org/p/iwrap
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Publish distribution to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-to-testpypi:
+    name: Publish iWrap distribution to TestPyPI
+    if: github.event_name == 'push'
+    needs:
+    - build
+    runs-on: ubuntu-22.04
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/iwrap
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Publish distribution to TestPyPI
+      uses: pypa/gh-action-pypi-publish@unstable/v1
+      with:
+        repository-url: https://test.pypi.org/legacy/
+        verbose: true

.readthedocs.yaml

@@ -0,0 +1,25 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  commands:
+    - pip install .
+    - pip install -r docs/requirements.txt
+    - cd docs && jupyter-book build .
+    # RTD expects the built HTML at: $READTHEDOCS_OUTPUT/html
+    - mkdir -p $READTHEDOCS_OUTPUT/html
+    - cp -a docs/_build/html/. $READTHEDOCS_OUTPUT/html/
+
+# Optionally set the Python requirements used to build documentation
+python:
+  install:
+    - requirements: docs/requirements.txt
+
+# Explicitly specify submodules
+submodules:
+  include: all

MANIFEST.in

@@ -2,6 +2,4 @@ recursive-include bin *
 recursive-include iwrap *
 include requirements*
 include README.md
-include LICENSE.md
-include versioneer.py
-include iwrap/_version.py
+include LICENSE.md

Makefile

@@ -24,7 +24,7 @@ all: iwrap_build
 install: install_dir install_iwrap install_module docs
 uninstall: uninstall_module uninstall_iwrap
 
-.PHONY: build/module/$(MODULEFILE) install_iwrap update_iwrap iwrap_build build_deps build_deps_clear help clean docs
+.PHONY: build/module/$(MODULEFILE) install_iwrap update_iwrap iwrap_build build_deps build_deps_clear help clean docs test-muscle3 build-muscle3-macro clean-muscle3
 
 
 check_already_installed:
@@ -104,13 +104,44 @@ help: install_dir
 	@echo -e "\tINSTALL_MOD: [$(INSTALL_MOD)]"
 	@echo -e "Version of the package - iWrap version:"
 	@echo -e "\tVERSION: [$(VERSION)]"
+	@echo -e "\n- MUSCLE3-specific targets:"
+	@echo -e "\ttest-muscle3        : Run MUSCLE3 integration tests"
+	@echo -e "\tbuild-muscle3-macro : Build MUSCLE3 macro model for tests"
+	@echo -e "\tclean-muscle3       : Clean MUSCLE3 test artifacts"
 
 docs:
 	@$(SHELL_SCRIPT)
 
 code-check:
 	pylint -E ./iwrap
 
-clean:
+# MUSCLE3-specific targets
+test-muscle3:
+	@echo "Running MUSCLE3 integration tests..."
+	@if [ -f tests/run-muscle3-tests.sh ]; then \
+		cd tests && ./run-muscle3-tests.sh; \
+	else \
+		echo "MUSCLE3 test script not found. Running pytest..."; \
+		$(PY_CMD) -m pytest tests/muscle3/ -v -m muscle3 || echo "pytest not available or tests failed"; \
+	fi
+
+build-muscle3-macro:
+	@echo "Building MUSCLE3 macro model for tests..."
+	@if [ -d tests/muscle3/macro ]; then \
+		$(MAKE) -C tests/muscle3/macro; \
+	else \
+		echo "MUSCLE3 macro directory not found at tests/muscle3/macro"; \
+	fi
+
+clean-muscle3:
+	@echo "Cleaning MUSCLE3 test artifacts..."
+	@$(RM) -rf tests/muscle3/run_*
+	@$(RM) -rf tests/muscle3/*/m3_actor
+	@$(RM) -rf tests/muscle3/actors/*/run_*
+	@$(RM) -rf tests/muscle3/actors/*/*/m3_actor
+	@$(RM) -rf tests/integration/muscle3/run_*
+	@echo "MUSCLE3 test artifacts cleaned"
+
+clean: clean-muscle3
 	rm -rf dist
 	rm -rf build

README.md

@@ -1,9 +1,21 @@
 # iWrap
 
+[![Read the Docs](https://img.shields.io/badge/docs-readthedocs-blue)](https://iwrap.readthedocs.io)
+
 iWrap is a modular component generator, implemented in Python, used for creating IMAS actors from physics models. This mechanism allows to integrate physics codes written in one language (Fortran, CPP) within complex computing scenarios designed in other language (e.g. Python).
 
 It's plug-in based modular design with clear separation of concerns allows to generate various types of actors and easily change data access paradigm (from dataset descriptor for AL to direct HDC data for instance)
 
+## Available Actor Types
+
+iWrap includes the following built-in actor generators:
+
+- **Python Actor**: Standard Python actors for straightforward Python integrations
+- **MUSCLE3 Actors** (optional): High-performance multiscale coupling framework
+  - MUSCLE3-Python: Python code with MUSCLE3 coupling
+  - MUSCLE3-CPP: C++ code with MUSCLE3 coupling
+  - MUSCLE3-Fortran: Fortran code with MUSCLE3 coupling
+
 For user conveniency it provides two kinds of interfaces: 
 * user friendly graphical interface that allows non-experienced users to define an actor in intuitive way 
 * command line interface foreseen for more advanced users that may want to e.g. automatise actor generation process using scripts.
@@ -14,10 +26,39 @@ To learn about iWrap, please follow `tutorials/README.md` to generate an interac
 
 We have also prepared HTML and Docker versions, so you can choose the one that suits you best.
 
+# Installation
+
+## Quick Install
+
+### Basic Installation (Core Only)
+```bash
+pip install iwrap
+```
+This installs iWrap with the standard Python actor generator.
+
+### Installation with MUSCLE3 Support
+```bash
+pip install iwrap[muscle3]
+```
+This enables MUSCLE3 actor generators (MUSCLE3-Python, MUSCLE3-CPP, MUSCLE3-Fortran).
+
+### Development Installation
+```bash
+pip install iwrap[all]
+```
+Installs all optional dependencies including MUSCLE3.
+
+## Verify Installation
+
+List available actor types:
+```bash
+iwrap --list-actor-types
+```
+
 # Configuration of working environment
 
 ## Downloading software
-    git clone ssh://git@git.iter.org/imex/iwrap.git
+    git clone https://github.com/iterorganization/iWrap.git
     cd iwrap
     git checkout <branch>
 

ci/muscle3/build-macro-model.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+source ci/muscle3/setup-test-env.sh  $* || exit 1
+echo "executing $(basename "$0")"
+cd ./tests/muscle3/macro
+make all
+

ci/muscle3/make-docs.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+
+source ci/muscle3/setup-test-env.sh  $@ || exit 1
+
+echo "-----------Create Python Virtual ENV-------------"
+# Remove Virtual env if already exists
+rm -rf venv
+python -m venv --system-site-packages venv
+#python -m venv venv
+
+echo "-----------Activate Python Virtual ENV-------------"
+source `pwd`/venv/bin/activate
+
+echo "-----------------PIP sphinx-rtd-theme------------"
+pip install sphinx-rtd-theme
+
+
+echo "--------------Report Python version--------------"
+echo "Python version: `python --version`"
+echo "Using python from: `which python`"
+
+
+echo "--------------Build documentation--------------"
+# PYTHONPATH set to allow sphinx find 'Read The Docs' theme
+PYTHONPATH=`pwd`/venv/lib//python3.11/site-packages/:$PYTHONPATH make docs
+# make docs
+
+echo "-----------Remove Python Virtual ENV-------------"
+rm -rf venv

ci/muscle3/setup-test-env.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+echo "executing $(basename "$0")"
+
+print_help() {
+    echo -e "Usage:"
+    echo -e "\t $0 [--use-installed|-i] [--help|-h]"
+    echo 
+    echo -e "optional arguments:"
+    echo -e "\t -i, --use-installed    use PIP installed or already loaded instance of plugins"
+    echo -e "\t -h, --help             show this help message and exit"
+}
+
+
+use_installed=false
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --use-installed|-i)
+       echo "WARNING: Using pre-loaded instance of plugins!"
+       use_installed=true
+      ;;
+    --help|-h)
+      print_help
+      exit 0
+      ;;
+    *)
+      printf "ERROR: Incorrect parameter: \"$1\"\n"
+      print_help
+      # exit 1
+  esac
+  shift
+done
+
+# setup system environment
+source ci/muscle3/st01-system-env.sh "$@" || exit 1
+
+# look if iWrap has been already loaded / configured
+if `which iwrap &> /dev/null` ; then
+    echo "WARNING: Using pre-loaded 'iWrap' from `which iwrap`!"
+
+else
+    echo "INFO: iWrap was not loaded! Loading 'iWrap' module!"
+    source ci/muscle3/st02-iwrap-load.sh "$@" || exit 1
+fi
+
+# check if 'local' or installed version should be used
+# if $use_installed ; then
+#     echo "WARNING: Using pre-loaded instance of plugins!"
+# else
+#     echo "INFO: Setting up plugins from local directory!"
+#     source ci/muscle3/st03-m3plugins-local.sh "$@" || exit 1
+# fi
+
+

ci/muscle3/st00-defs.sh

@@ -0,0 +1,19 @@
+# auxiliary functions definitions
+
+echo "executing $(basename "$0")"
+function yell () 
+{ 
+  echo "$0: $*" >&2
+}
+
+function die () 
+{ 
+  yell "$*"; exit 1
+}
+
+function try () 
+{ 
+  "$@" || die "cannot $*" 
+}
+
+