update on documents

wahln · wahln · commit 6ee0081a4a01 · 2025-05-26T10:51:16.000+02:00
diff --git a/docs/algorithms/dicom.rst b/docs/algorithms/dicom.rst
@@ -0,0 +1,14 @@
+.. _dicom:
+
+.. toctree::
+   :maxdepth: 2
+
+=====================
+DICOM Import & Export
+=====================
+
+.. automodule:: matRad.dicom
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:
diff --git a/docs/algorithms/dosecalc.rst b/docs/algorithms/dosecalc.rst
@@ -1,8 +1,14 @@
-.. _dose_calc:
+.. _dosecalc:
 
 .. toctree::
    :maxdepth: 2
 
 ================
 Dose Calculation
-================
+================
+
+.. automodule:: matRad.doseCalc
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:
diff --git a/docs/algorithms/optimization.rst b/docs/algorithms/optimization.rst
@@ -0,0 +1,11 @@
+.. _optimization:
+
+============
+Optimization
+============
+
+.. automodule:: matRad.optimization
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:
diff --git a/docs/api/config.rst b/docs/api/config.rst
@@ -0,0 +1,16 @@
+.. _config:
+
+The global configuration class
+==============================
+
+matRad's global configuration class is used to set up the environment and configuration for the matRad application. 
+It is implemented as a Singleton pattern and thus consistent throughout a matRad session.
+
+At the core, the class handles user folders, caches the environment (Matlab/Octave), provides matRad's version, and stores default parameters. 
+The class also provides logging functionality enabling control over output via log levels.
+
+.. autoclass:: matRad.MatRad_Config
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :private-members:
diff --git a/docs/cite.rst b/docs/cite.rst
@@ -0,0 +1,14 @@
+.. _cite:
+
+===================
+How to cite matRad?
+===================
+
+.. _citepubs:
+Cite our publications
+---------------------
+
+.. _citesoftware:
+Direct Software Citation (zenodo)
+---------------------------------
+
diff --git a/docs/conf.py b/docs/conf.py
@@ -7,6 +7,8 @@
 version = "3.1.0"
 release = "3.1.0"
 
+html_theme = "sphinx_rtd_theme" #pip install sphinx-rtd-theme
+
 extensions = [
     'sphinx.ext.autodoc',
     'sphinxcontrib.matlab', 
@@ -16,10 +18,12 @@
 primary_domain = "mat"
 
 matlab_src_dir = os.path.join(os.path.dirname(__file__), '../')
-matlab_auto_link = "all"
+matlab_auto_link = "basic"
 
 matlab_show_property_default_value = True
+matlab_show_property_specs = True
 matlab_class_signature = True
+matlab_short_links = True
 
 autoclass_content = "both"
 autodoc_member_order = "bysource"
diff --git a/docs/datastructures/basedata/particles.rst b/docs/datastructures/basedata/particles.rst
@@ -1,8 +1,5 @@
 .. _basedata_particles:
 
-.. toctree::
-   :maxdepth: 2
-
 ========================
 Particle Base Data File
 ========================
@@ -27,6 +24,7 @@ machine.meta.SAD
 ^^^^^^^^^^^^^^^^
 This subfield holds the geometrical source to axis distance in millimeter. In case of the generic base data set, we use a value of 10000 [mm].
 
+.. _BAMStoIsoDist:
 machine.meta.BAMStoIsoDist
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 This subfield depicts the geometrical distance from the beam application monitoring system/beam nozzle to the isocenter. For the generic base data set we use a value of 2000 [mm].
@@ -41,7 +39,7 @@ This subfield contains an array of structures holding the corresponding depth-de
 
 machine.data.energy
 ^^^^^^^^^^^^^^^^^^^
-Initial beam energy in MeV/u.
+Initial beam energy in MeV/u. Internally, this is used mainly as an identifier for the entry and does not necessarily correspond to an exact energy at the nozzle, for example.
 
 machine.data.depths
 ^^^^^^^^^^^^^^^^^^^
@@ -57,7 +55,7 @@ This field allows to consider a pencil beam offset caused by passive beam line e
 
 machine.data.Z
 ^^^^^^^^^^^^^^
-This field holds the integrated depth dose profiles of the corresponding radiation modality. Regarding units, we refer to the base data section in the section :ref:`Dose influence matrix calculation <dose_calc>`.
+This field holds the integrated depth dose profiles of the corresponding radiation modality. Regarding units, we refer to the base data section in the section :ref:`Dose influence matrix calculation <dosecalc>`.
 
 machine.data.sigma 
 ^^^^^^^^^^^^^^^^^^^
@@ -82,3 +80,7 @@ Relative weight between the narrow (sigma1) and the broad (sigma) Gaussian compo
 machine.data.initFocus
 ^^^^^^^^^^^^^^^^^^^^^^
 Let numFoci be the number of available focus indices and machine.data.initFocus hold three subfields named 'dist', 'sigma' and 'SisFWHMAtIso' of the following dimensions numFoci x N, numFoci x N and numFoci x 1 whereas N indicates the number of values used in the look up table. SisFWHMAtIso describes for each focus index the initial FWHM at isocenter. In contrast, 'dist' and 'sigma' depict a look up table to model the particle beam spread in air. In the generic proton and carbon base data set we do not model beam widening in air from the beam nozzle to the patient surface (although the code is capable of). Therefore, machine.data.initFocus(1).sigma is a constant value over a distance from 0 to 20000 [mm].
+
+machine.data.energySpectrum
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Sotres the energyspectrum at the nozzle (whose distance is taken from BAMStoIsoDist__)
diff --git a/docs/datastructures/basedata/photons.rst b/docs/datastructures/basedata/photons.rst
@@ -0,0 +1,5 @@
+.. _basedata_photons:
+
+======================
+Photon Base Data File
+======================
diff --git a/docs/datastructures/cort.rst b/docs/datastructures/cort.rst
@@ -0,0 +1,5 @@
+.. _cort:
+
+================
+The CORT Dataset
+================
diff --git a/docs/faq.rst b/docs/faq.rst
@@ -10,6 +10,17 @@ Frequently Asked Questions
 While this site attempts to cover a set of frequently asked questions, it is not exhaustive.
 We suggest to visit our `GitHub Discussion Forum <https://github.com/e0404/matRad/discussions>`_ for Questions and Answers from the Community.
 
+.. admonition:: How to cite matRad?
+    :class: dropdown
+
+    If you use matRad, please consider :ref:`citing our publications <citepubs>` as well as :ref:`the software version <citesoftware>` you are using directly.
+
+.. admonition:: Can I run matRad without a MATLAB installation?
+    :class: dropdown
+
+    Yes, if you only need the graphical user interface you can also use the commpiled standalone. 
+    If you need to work with the code, check our :ref:`guide <octave>` on running matRad with `GNU Octave <http://www.octave.org>`_
+
 .. admonition:: How can I model custom particle machines in matRad?
     :class: dropdown
 
@@ -33,4 +44,3 @@ We suggest to visit our `GitHub Discussion Forum <https://github.com/e0404/matRa
     For further information refer to : 
     * `matRad Issue #550 <https://github.com/e0404/matRad/issues/550>_`
     * `MATLAB Answers thread <https://de.mathworks.com/matlabcentral/answers/422244-why-do-buttons-apps-or-the-editor-in-matlab-respond-slowly-or-hang-on-macos>_`
- 
diff --git a/docs/guides/coords.rst b/docs/guides/coords.rst
@@ -0,0 +1,5 @@
+.. _coords:
+
+============================
+The matRad Coordinate System
+============================
diff --git a/docs/guides/octave.rst b/docs/guides/octave.rst
@@ -0,0 +1,5 @@
+.. _octave:
+
+=============================
+How to run matRad with Octave
+=============================
diff --git a/docs/guides/plan.rst b/docs/guides/plan.rst
@@ -0,0 +1,7 @@
+.. _plan:
+
+===========================
+How to configure your plan?
+===========================
+
+The :ref:`pln struct <pln>` is the central configuration data structure for matRad.
diff --git a/docs/guides/requirements.rst b/docs/guides/requirements.rst
@@ -0,0 +1,5 @@
+.. _requirements:
+
+===========================
+Minimum System Requirements
+===========================
diff --git a/docs/guides/visualization.rst b/docs/guides/visualization.rst
@@ -0,0 +1,5 @@
+.. _visualization:
+
+====================
+matRad Visualization
+====================
diff --git a/docs/index.rst b/docs/index.rst
@@ -68,11 +68,11 @@ Please let us know if we can include your center, or if you have discontinued th
    :caption: Contents
    :glob:
 
-   index
    about
    settingup
    techdoc
    modules
    faq
+   cite
    genindex
-   modindex
+   MATLAB Module Index <mat-modindex.html#http://>
diff --git a/docs/modules.rst b/docs/modules.rst
@@ -1,7 +1,9 @@
-matRad
-============
+matRad Modules
+==============
 
 .. automodule:: matRad
-    :members:
-    :show-inheritance:
-    :undoc-members:
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:
+
diff --git a/docs/techdoc.rst b/docs/techdoc.rst
@@ -17,46 +17,67 @@ The four main parts of the matRad workflow are
 
 Information about the individual modules is given in the following subsections:
 
-`Set treatment plan parameters <Set-treatment-plan-parameters>`__
+:ref:`Set treatment plan parameters <plan>`
 
-`Dose influence matrix
-calculation <Dose-influence-matrix-calculation>`__
+:ref:`Dose influence matrix calculation <dosecalc>`
 
-`Fluence optimization <Fluence-optimization>`__
+:ref:`Fluence optimization <optimization>` (potentiall followed by sequencing)
 
-`Visualization <Visualization>`__
+:ref:`Visualization <visualization>`
 
 How to cite matRad
 ------------------
 
-`matRad publications <How-to-cite-matRad>`__
+:ref:`matRad publications <cite>`
 
 .. _httpsrawgitcomwikie0404matradimagesmatrad_blanksvg--height--25pxs-most-important-matlab-variables:
 
+.. _matrad_variables:
+
 |matRad_logo|'s most important Matlab variables
 -----------------------------------------------
 
-`pln-struct <pln>`__ Treatment plan information
+:ref:`pln-struct <pln>` Treatment plan information
+
+:ref:`ct-struct <ct>` CT-data
+
+:ref:`cst-cell array <cst>` Structure sets, inverse planning objectives, and other meta-information
+
+:ref:`stf-struct <stf>` Steering information
 
-`ct-struct <ct>`__ CT-data
+:ref:`dij-struct <dij>` Dose influence data
 
-`cst-cell array <cst>`__ Structure sets, inverse planning objectives, and other meta-information
+:ref:`result-struct <result>` Resulting dose distribution, RBE cube etc..
 
-`stf-struct <stf>`__ Steering information
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :glob:
 
-`dij-struct <dij>`__ Dose influence data
+   datastructures/*
 
-`result-struct <result>`__ Resulting dose distribution, RBE cube etc..
+|matRad_logo|'s top-level functions
+-----------------------------------
+
+:ref:`MatRad_Config <config>` Global configuration class
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+   :glob:
+
+   api/*
 
 Additional information
 ----------------------
 
-`How to run matRad with Octave <How-to-run-matRad-with-Octave>`__
+:ref:`How to run matRad with Octave <octave>`
+
+:ref:`matRad coordinate system <coords>`
 
-`matRad coordinate system <The-matRad-coordinate-system>`__
+:ref:`The CORT dataset <cort>`
 
-`The CORT dataset <The-CORT-dataset>`__
+:ref:`DICOM import <dicom>`
 
-`DICOM import <The-dicom-import>`__
+:ref:`Minimum system requirements <requirements>`
 
-`Minimum system requirements <min-sys-requirements>`__
