From 09b0a91be8135470e7784c6546077e43c070923b Mon Sep 17 00:00:00 2001 From: AhmedBasem Date: Wed, 13 Mar 2024 08:21:02 +0200 Subject: [PATCH 01/10] Generate API documentation using Sphinx. --- .github/workflows/sphinx.yml | 51 ++++++++++++++++++++++++++++++++++++ doc/Makefile | 20 ++++++++++++++ doc/conf.py | 36 +++++++++++++++++++++++++ doc/index.rst | 18 +++++++++++++ requirements.txt | 4 ++- 5 files changed, 128 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/sphinx.yml create mode 100644 doc/Makefile create mode 100644 doc/conf.py create mode 100644 doc/index.rst diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml new file mode 100644 index 0000000..777e30a --- /dev/null +++ b/.github/workflows/sphinx.yml @@ -0,0 +1,51 @@ +name: Build Documentation + +on: + push: + branches: + - 'main' +permissions: + contents: read + pages: write + id-token: write +jobs: + build: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Setup Pages + uses: actions/configure-pages@v4 + - name: Set up Python + id: setup_python + uses: actions/setup-python@v5 + with: + python-version: "3.11" + - name: Cache pip + uses: actions/cache@v3 + id: pip-cache + with: + key: ${{ runner.os }}-${{ env.pythonLocation }}-pip-${{ hashFiles('**/requirements.txt') }} + path: ${{ env.pythonLocation }} + if: steps.pip-cache.outputs.cache-hit != 'true' + + - name: Install dependencies + run: | + pip install -r requirements.txt + + - name: Build html + run: | + sphinx-apidoc -o doc src + cd doc/ + make html + + - name: Upload docs artifact + uses: actions/upload-pages-artifact@v3 + with: + path: 'doc/_build/html' + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..41c270b --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# 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 diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..e268db2 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,36 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +import os +import sys + +sys.path.insert(0, os.path.abspath("..")) + +project = 'TF2.4 IVIM MRI Code Collection' +copyright = '2024, OSIPI' +author = 'OSIPI team' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ["sphinx.ext.todo", "sphinx.ext.viewcode", "sphinx.ext.autodoc"] + +templates_path = ['_templates'] +exclude_patterns = ['Thumbs.db', '.DS_Store'] + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +html_show_sphinx = False + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +html_show_copyright = False + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'sphinx_rtd_theme' +html_static_path = ['_static'] diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..86de157 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,18 @@ +.. TF2.4 IVIM MRI Code Collection documentation master file, created by + sphinx-quickstart on Wed Mar 6 00:06:13 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to TF2.4 IVIM MRI Code Collection's documentation! +========================================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + modules + +Indices and tables +================== + +* :ref:`modindex` diff --git a/requirements.txt b/requirements.txt index 0f3e4d7..31897a3 100644 --- a/requirements.txt +++ b/requirements.txt @@ -10,4 +10,6 @@ scienceplots cvxpy zenodo-get pytest -tqdm \ No newline at end of file +tqdm +sphinx +sphinx_rtd_theme \ No newline at end of file From 255618c5dc2c0925ef0051c3c7c977bf4205c19e Mon Sep 17 00:00:00 2001 From: AhmedBasem Date: Mon, 18 Mar 2024 02:04:32 +0200 Subject: [PATCH 02/10] Integrate the algorithms figures into the documentation website. --- {doc => docs}/Makefile | 0 {doc => docs}/conf.py | 0 docs/figures.rst | 45 +++++++++++++++++++++++++++++++++++++++++ {doc => docs}/index.rst | 3 ++- 4 files changed, 47 insertions(+), 1 deletion(-) rename {doc => docs}/Makefile (100%) rename {doc => docs}/conf.py (100%) create mode 100644 docs/figures.rst rename {doc => docs}/index.rst (94%) diff --git a/doc/Makefile b/docs/Makefile similarity index 100% rename from doc/Makefile rename to docs/Makefile diff --git a/doc/conf.py b/docs/conf.py similarity index 100% rename from doc/conf.py rename to docs/conf.py diff --git a/docs/figures.rst b/docs/figures.rst new file mode 100644 index 0000000..e979a31 --- /dev/null +++ b/docs/figures.rst @@ -0,0 +1,45 @@ +Algorithm Analysis Figures +=========== + +.. raw:: html + + + + + + + Algorithm Analysis Figures + + + +

Diffusion grid for limited algorithms:

+ +

Diffusion grid for all algorithms:

+ + +

Perfusion grid for limited algorithms:

+ +

Perfusion grid for all algorithms:

+ + +

Perfusion fraction grid for limited algorithms:

+ +

Perfusion fraction grid for all algorithms:

+ + +

Fitted curves:

+ +

Curve plot:

+ +

Algorithm Fitting duration:

+ + + + diff --git a/doc/index.rst b/docs/index.rst similarity index 94% rename from doc/index.rst rename to docs/index.rst index 86de157..06bcfa9 100644 --- a/doc/index.rst +++ b/docs/index.rst @@ -7,9 +7,10 @@ Welcome to TF2.4 IVIM MRI Code Collection's documentation! ========================================================== .. toctree:: - :maxdepth: 2 + :maxdepth: 4 :caption: Contents: + figures modules Indices and tables From 6387588c5aa37b457ee28800d407f191e91c4c42 Mon Sep 17 00:00:00 2001 From: AhmedBasem Date: Mon, 18 Mar 2024 02:06:02 +0200 Subject: [PATCH 03/10] Add the figures artifact to the docs folder before building the website. --- .github/workflows/sphinx.yml | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml index 777e30a..2b8e262 100644 --- a/.github/workflows/sphinx.yml +++ b/.github/workflows/sphinx.yml @@ -35,16 +35,22 @@ jobs: run: | pip install -r requirements.txt + - name: Download figures artifact + uses: actions/download-artifact@v3 + with: + name: Figures + - name: Build html run: | - sphinx-apidoc -o doc src + mv Figures docs/_static/ + sphinx-apidoc -o docs src cd doc/ make html - name: Upload docs artifact uses: actions/upload-pages-artifact@v3 with: - path: 'doc/_build/html' + path: 'docs/_build/html' - name: Deploy to GitHub Pages id: deployment From 67258430c7be125e648e82734c3d3af69664aa1d Mon Sep 17 00:00:00 2001 From: AhmedBasem Date: Mon, 18 Mar 2024 04:46:31 +0200 Subject: [PATCH 04/10] Fix pdf path --- docs/figures.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/figures.rst b/docs/figures.rst index e979a31..1291f6a 100644 --- a/docs/figures.rst +++ b/docs/figures.rst @@ -20,26 +20,26 @@ Algorithm Analysis Figures

Diffusion grid for limited algorithms:

- +

Diffusion grid for all algorithms:

- +

Perfusion grid for limited algorithms:

- +

Perfusion grid for all algorithms:

- +

Perfusion fraction grid for limited algorithms:

- +

Perfusion fraction grid for all algorithms:

- +

Fitted curves:

- +

Curve plot:

- +

Algorithm Fitting duration:

- + From c05d0cc8c7f4f5d3e59b1860c7b1b51fd253395e Mon Sep 17 00:00:00 2001 From: AhmedBasem Date: Mon, 18 Mar 2024 04:47:32 +0200 Subject: [PATCH 05/10] Use figures artifact generated by analysis.yml workflow --- .github/workflows/sphinx.yml | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml index 2b8e262..0ff88c4 100644 --- a/.github/workflows/sphinx.yml +++ b/.github/workflows/sphinx.yml @@ -35,16 +35,20 @@ jobs: run: | pip install -r requirements.txt + # Action to download artifacts from a different workflow (analysis.yml) - name: Download figures artifact - uses: actions/download-artifact@v3 + uses: dawidd6/action-download-artifact@v3 with: + workflow: analysis.yml name: Figures + branch: main - name: Build html run: | - mv Figures docs/_static/ + mkdir docs/_static + mv *.pdf docs/_static/ sphinx-apidoc -o docs src - cd doc/ + cd docs/ make html - name: Upload docs artifact From bbb6358d879796dd29f8e9e608e8f8a4959690e7 Mon Sep 17 00:00:00 2001 From: AhmedBasem Date: Mon, 18 Mar 2024 15:19:44 +0200 Subject: [PATCH 06/10] Deploy when the new figures are generated. --- .github/workflows/sphinx.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml index 0ff88c4..4c5731e 100644 --- a/.github/workflows/sphinx.yml +++ b/.github/workflows/sphinx.yml @@ -4,6 +4,10 @@ on: push: branches: - 'main' + workflow_run: + workflows: ["analysis.yml"] + types: + - completed permissions: contents: read pages: write From fbbd3f0afcb3040e94c8b4cc61ce19932ed38e84 Mon Sep 17 00:00:00 2001 From: AhmedBasem Date: Tue, 19 Mar 2024 13:43:47 +0200 Subject: [PATCH 07/10] use the official download method. --- .github/workflows/analysis.yml | 1 + .github/workflows/sphinx.yml | 28 +++++++++++++++++++++++----- 2 files changed, 24 insertions(+), 5 deletions(-) diff --git a/.github/workflows/analysis.yml b/.github/workflows/analysis.yml index 55f59cf..9a734b9 100644 --- a/.github/workflows/analysis.yml +++ b/.github/workflows/analysis.yml @@ -5,6 +5,7 @@ on: branches: - 'main' - 'analysis/**' + - 'test-docs' jobs: algorithms: diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml index 4c5731e..b0fbeb7 100644 --- a/.github/workflows/sphinx.yml +++ b/.github/workflows/sphinx.yml @@ -40,16 +40,34 @@ jobs: pip install -r requirements.txt # Action to download artifacts from a different workflow (analysis.yml) - - name: Download figures artifact - uses: dawidd6/action-download-artifact@v3 + - name: 'Download artifact' + uses: actions/github-script@v6 with: - workflow: analysis.yml - name: Figures - branch: main + script: | + let allArtifacts = await github.rest.actions.listWorkflowRunArtifacts({ + owner: context.repo.owner, + repo: context.repo.repo, + run_id: context.payload.workflow_run.id, + }); + let matchArtifact = allArtifacts.data.artifacts.filter((artifact) => { + return artifact.name == "Figures" + })[0]; + let download = await github.rest.actions.downloadArtifact({ + owner: context.repo.owner, + repo: context.repo.repo, + artifact_id: matchArtifact.id, + archive_format: 'zip', + }); + let fs = require('fs'); + fs.writeFileSync(`${process.env.GITHUB_WORKSPACE}/Figures.zip`, Buffer.from(download.data)); + + - name: 'Unzip artifact' + run: unzip Figures.zip - name: Build html run: | mkdir docs/_static + ls mv *.pdf docs/_static/ sphinx-apidoc -o docs src cd docs/ From 85b13d7668bed858f3d167d8b2ae24c7683d9931 Mon Sep 17 00:00:00 2001 From: AhmedBasem Date: Wed, 20 Mar 2024 21:56:43 +0200 Subject: [PATCH 08/10] Prevent deploying on every push --- .github/workflows/sphinx.yml | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml index b0fbeb7..6c082f4 100644 --- a/.github/workflows/sphinx.yml +++ b/.github/workflows/sphinx.yml @@ -1,11 +1,8 @@ -name: Build Documentation +name: Build & Deploy Documentation on: - push: - branches: - - 'main' workflow_run: - workflows: ["analysis.yml"] + workflows: [Algorithm Analysis] types: - completed permissions: From b7d5e2f283a652a149be4e6c1ce3e4a00628d77c Mon Sep 17 00:00:00 2001 From: AhmedBasem Date: Thu, 21 Mar 2024 16:30:40 +0200 Subject: [PATCH 09/10] Generate docs even on analysis workflow failure. --- .github/workflows/analysis.yml | 1 - .github/workflows/sphinx.yml | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/analysis.yml b/.github/workflows/analysis.yml index 9a734b9..55f59cf 100644 --- a/.github/workflows/analysis.yml +++ b/.github/workflows/analysis.yml @@ -5,7 +5,6 @@ on: branches: - 'main' - 'analysis/**' - - 'test-docs' jobs: algorithms: diff --git a/.github/workflows/sphinx.yml b/.github/workflows/sphinx.yml index 6c082f4..f3ecfd3 100644 --- a/.github/workflows/sphinx.yml +++ b/.github/workflows/sphinx.yml @@ -38,6 +38,7 @@ jobs: # Action to download artifacts from a different workflow (analysis.yml) - name: 'Download artifact' + if: ${{ github.event.workflow_run.conclusion == 'success' }} uses: actions/github-script@v6 with: script: | @@ -64,7 +65,6 @@ jobs: - name: Build html run: | mkdir docs/_static - ls mv *.pdf docs/_static/ sphinx-apidoc -o docs src cd docs/ From ab9354bf5f0bd021490545c9403ccddeaf5eaf28 Mon Sep 17 00:00:00 2001 From: AhmedBasem Date: Thu, 21 Mar 2024 16:32:27 +0200 Subject: [PATCH 10/10] rename docs workflow. --- .github/workflows/{sphinx.yml => documentation.yml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .github/workflows/{sphinx.yml => documentation.yml} (100%) diff --git a/.github/workflows/sphinx.yml b/.github/workflows/documentation.yml similarity index 100% rename from .github/workflows/sphinx.yml rename to .github/workflows/documentation.yml