Repository: jfcabana/omg_dosimetry (language: python)

Issue:
Changes needed for a correct packaging



Discussion / hints:

Fix patch:
diff --git a/.gitignore b/.gitignore
index e517d32..c418707 100644
--- a/.gitignore
+++ b/.gitignore
@@ -63,4 +63,7 @@ __pycache__/
 
 # Fichiers de calibration
 *.pkl
-*.pdf
\ No newline at end of file
+*.pdf
+
+# Builded web page with sphinx
+docs/build
\ No newline at end of file
diff --git a/.readthedocs.yml b/.readthedocs.yml
new file mode 100644
index 0000000..e5d4556
--- /dev/null
+++ b/.readthedocs.yml
@@ -0,0 +1,30 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/source/conf.py
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+  #jobs:
+  #  pre_build:
+      # Generate on-the-fly Sphinx configuration from Jupyter Book's _config.yml
+      #- "jupyter-book config sphinx docs/Jupyter_Book/"
+
+python:
+   install:
+   - requirements: requirements_read_the_docs.txt
+#   - method: pip
+#     path: .
+
+formats:
+  - pdf
+  - epub
\ No newline at end of file
diff --git a/README.md b/README.rst
similarity index 87%
rename from README.md
rename to README.rst
index 77caf51..6a1952c 100644
--- a/README.md
+++ b/README.rst
@@ -1,6 +1,10 @@
-![alt text](https://github.com/jfcabana/omg_dosimetry/blob/OMG_master/src/omg_dosimetry/OMG_Logo.png?raw=true)
+OMG Dosimetry
+=============
 
-# Optimized Multichannel Gafchromic Dosimetry (OMG Dosimetry)
+.. image:: https://github.com/jfcabana/omg_dosimetry/blob/OMG_master/src/omg_dosimetry/OMG_Logo.png?raw=true
+    :width: 100%
+    :target: https://github.com/jfcabana/omg_dosimetry
+    :align: center
 
 With OMG Dosimetry, you can easily perform film calibration, film-to-dose conversion, and dose analysis.
 
@@ -8,7 +12,8 @@ Demonstration files are provided for each module to get you started quickly.
 Code is heavily commented so you can follow along and andapt it for your personnal usage.
 
 
-## Gafchromic calibration module
+Gafchromic calibration module
+-----------------------------
 
 The calibration module computes multichannel calibration curves from scanned films. 
 
@@ -19,7 +24,8 @@ This requires exposing long film strips and scanning them perpendicular to the s
 To account for non-flat beam profiles, the output from an ICProfiler acquired at the same time as film exposure can be given as input to correct for beam shape.
 Alternatively, the lateral scanner response correction can be turned off, then a single calibration curve is computed for all pixels.
 
-### Features
+Features
+^^^^^^^^
 
 - Automatically loads multiple images in a folder, average multiple copies of same image and stack different scans together.
 - Automatically detect film strips position and size, and define ROIs inside these film strips.
@@ -30,12 +36,14 @@ Alternatively, the lateral scanner response correction can be turned off, then a
 - Publish PDF report
 
 
-## Film-to-dose module
+Film-to-dose module
+-------------------
 
 The film-to-dose module performs optimized multichannel conversion from scanned gafchromic films to absolute dose.
 It uses the optimized multichannel method from Mayer *et al* (https://doi.org/10.1118/1.3694100) and calibration curves obtained with the calibration module.
 
-### Features
+Features
+^^^^^^^^
 
 - Multiple scans of same film are loaded and averaged automatically
 - Automatic film detection and crop
@@ -47,11 +55,13 @@ It uses the optimized multichannel method from Mayer *et al* (https://doi.org/10
 - Publish PDF report
 
 
-## Dose analysis module
+Dose analysis module
+--------------------
 
 The dose analysis module performs in-depth comparison from film dose to reference dose image from treatment planning system.
 
-### Features
+Features
+^^^^^^^^
 
 - Perform registration by identifying fiducial markers to set isocenter
 - Interactive display of analysis results (gamma map, relative error, dose profiles)
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..d0c3cbf
--- /dev/null
+++ b/docs/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     = source
+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)
diff --git a/docs/make.bat b/docs/make.bat
new file mode 100644
index 0000000..dc1312a
--- /dev/null
+++ b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/source/analysis.rst b/docs/source/analysis.rst
new file mode 100644
index 0000000..a719f4b
--- /dev/null
+++ b/docs/source/analysis.rst
@@ -0,0 +1,9 @@
+===============
+Analysis module
+===============
+
+Overview
+--------
+
+.. automodule:: omg_dosimetry.analysis
+    :no-members:
\ No newline at end of file
diff --git a/docs/source/calibration.rst b/docs/source/calibration.rst
new file mode 100644
index 0000000..9f44496
--- /dev/null
+++ b/docs/source/calibration.rst
@@ -0,0 +1,21 @@
+==================
+Calibration module
+==================
+
+Overview
+--------
+
+.. automodule:: omg_dosimetry.calibration
+    :no-members:
+
+
+API Documentation
+=================
+
+Main classes
+------------
+
+These are the classes a typical user may interface with.
+
+.. autoclass:: omg_dosimetry.calibration.LUT
+    :members:
diff --git a/docs/source/conf.py b/docs/source/conf.py
new file mode 100644
index 0000000..9bc9fa7
--- /dev/null
+++ b/docs/source/conf.py
@@ -0,0 +1,37 @@
+# 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
+
+project = 'OMG dosimetry (beta)'
+copyright = '2023, Jean-François Cabana and Luis Alfonso Olivares Jiménez'
+author = 'Jean-François Cabana and Luis Alfonso Olivares Jiménez'
+
+# The short X.Y version.
+version = "1.4"
+# The full version, including alpha/beta/rc tags.
+release = "1.4.2"
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx_contributors',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.napoleon',
+    'sphinx_copybutton',
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "furo"
+html_static_path = ['_static']
diff --git a/docs/source/index.rst b/docs/source/index.rst
new file mode 100644
index 0000000..8cbd564
--- /dev/null
+++ b/docs/source/index.rst
@@ -0,0 +1,27 @@
+.. omg_dosimetry documentation master file, created by
+   sphinx-quickstart on Mon Jun 19 19:04:06 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+.. include:: ../../README.rst
+
+.. toctree::
+   :hidden:
+   :caption: Introducton:
+
+   installation
+
+.. toctree::
+   :hidden:
+   :caption: Modules:
+
+   calibration
+   tiff2dose
+   analysis
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
new file mode 100644
index 0000000..a404796
--- /dev/null
+++ b/docs/source/installation.rst
@@ -0,0 +1,80 @@
+.. _installation:
+
+============
+Installation
+============
+
+Installing OMG Dosimetry is easy no matter your python skills! Determine where you are at 
+and then read the relevant section:
+
+I know Python
+=============
+
+Python best practices recommend creating separate virtual environments for your different applications,
+to avoid dependency version conflicts. The following commands will install a dedicated Python environment for OMG Dosimetry using conda. 
+
+.. code-block:: bash
+
+    $ conda create --name omg_d python=3.10
+    $ pip install omg-dosimetry
+
+.. _dependencies:
+
+Dependencies
+------------
+
+OMG Dosimetry, as a scientific package, has fairly standard scientific dependencies (>= means at least that version or newer).
+Installing the package via ``pip`` will install these for you:
+
+.. literalinclude:: ../../requirements_pip.txt
+
+I'm new to Python
+=================
+
+That's okay! If you're not a programmer at all you'll have a few things to do to get up. Using OMG Dosimetry requires not just the base language Python, but a few dependencies as well.
+Since most physicists don't program, or if they do it's in MATLAB, this section will help jumpstart your use of not
+just OMG Dosimetry but Python in general and all its wonderful goodness! Getting started with Python takes some work to
+get set up, but it's well worth the effort.
+
+.. _distro_stack:
+
+Get a Distribution Stack
+------------------------
+
+Scientific computing with Python requires some specialized packages which require some specialized computing libraries.
+While it's possible you have those libraries (for some odd reason), it's not likely. Thus, it's often best to install
+the libraries *pre-compiled*. There are several options out there; I'll list just a few. Be sure to download the 3.x version,
+preferably the newest:
+
+* `Anaconda <https://www.anaconda.com/download>`_ provides this one-stop-shop for tons of
+  scientific libraries in an easy to install format. Just download and run the installer. If you don't want to install
+  all 200+ packages, a slimmer option exists: `Miniconda <https://docs.conda.io/en/latest/miniconda.html>`_, which only installs
+  ``conda`` and python installation tools.
+  Here's the Anaconda `Start guide <https://docs.anaconda.com/free/anaconda/#installation>`_.
+
+Install OMG Dosimetry
+---------------------
+
+After Anaconda has been installed, open Anaconda Prompt. Inside it (a window with black background), run the following commands:
+
+.. code-block:: bash
+
+    $ conda create --name omg_d python=3.10
+    $ pip install omg-dosimetry
+
+Get an IDE
+^^^^^^^^^^
+
+* `Spyder <https://www.spyder-ide.org/>`_ - A MATLAB-like IDE with similar layout, preferred by many working in the scientific realm.
+  Here are the `Spyder docs <https://docs.spyder-ide.org/current/index.html>`_.
+
+  .. note:: Spyder is part of the Anaconda distribution.
+
+  .. image:: https://docs.spyder-ide.org/current/_images/mainwindow_default_1610.png
+     :height: 400px
+     :width: 600px
+
+Inspiration
+^^^^^^^^^^^
+
+This installation guide is heavily inspired by `GitHub's pylinac instructions <https://pylinac.readthedocs.io/en/latest/installation.html>`_.
diff --git a/docs/source/tiff2dose.rst b/docs/source/tiff2dose.rst
new file mode 100644
index 0000000..a4a7902
--- /dev/null
+++ b/docs/source/tiff2dose.rst
@@ -0,0 +1,9 @@
+===================
+Tiff to Dose module
+===================
+
+Overview
+--------
+
+.. automodule:: omg_dosimetry.tiff2dose
+    :no-members:
\ No newline at end of file
diff --git a/pyproject.toml b/pyproject.toml
index a45ac1a..33d3948 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -12,7 +12,7 @@ maintainers = [
   {name = "Luis Alfonso Olivares Jimenez", email = "alfonso.cucei.udg@gmail.com"}
 ]
 description = "Optimized Multichannel Gafchromic Dosimetry (OMG Dosimetry)"
-readme = "README.md"
+readme = "README.rst"
 requires-python = ">=3.7, <3.11"
 classifiers = [
     "Programming Language :: Python :: 3",
@@ -22,10 +22,13 @@ classifiers = [
 dependencies = [
   "pymedphys~=0.39",
   "pylinac~=3.7",
+  "spyder~=5.3",
 ]
 
 [project.urls]
-"Homepage" = "https://github.com/jfcabana/omg_dosimetry"
+homepage = "https://omg-dosimetry.readthedocs.io/en/latest/"
+repository = "https://github.com/jfcabana/omg_dosimetry"
+Bug-Tracker = "https://github.com/jfcabana/omg_dosimetry/issues"
 
 [tool.hatch.build]
 exclude = [
diff --git a/requirements_pip.txt b/requirements_pip.txt
new file mode 100644
index 0000000..4289927
--- /dev/null
+++ b/requirements_pip.txt
@@ -0,0 +1,3 @@
+pymedphys~=0.39
+pylinac~=3.7
+spyder~=5.3
\ No newline at end of file
diff --git a/requirements_read_the_docs.txt b/requirements_read_the_docs.txt
new file mode 100644
index 0000000..4bf1187
--- /dev/null
+++ b/requirements_read_the_docs.txt
@@ -0,0 +1,7 @@
+furo
+matplotlib
+numpy
+sphinx
+sphinx-copybutton
+sphinx_contributors
+omg_dosimetry
\ No newline at end of file


Test patch:
diff --git a/requirements.txt b/requirements_test.txt
similarity index 100%
rename from requirements.txt
rename to requirements_test.txt