Merge branch 'refactor/docstrings' into 'develop'

Refactor/docstrings

See merge request e040/e0404/pyRadPlan!83

Author: wahln

pyRadPlan/__init__.py

@@ -1,4 +1,28 @@
-"""pyRadPlan is a Python package for radiation therapy treatment planning."""  # noqa: N999
+"""
+Python package for radiation therapy treatment planning.
+
+We recommend reading the documentation on `GitHub <https://github.com/e0404/pyRadPlan>`_.
+
+This package provides
+- Core classes and functions for treatment planning.
+- Dose influence matrix calculations and data structures.
+- Physical and biological quantities for treatment planning.
+- Optimization and analysis tools for radiation therapy plans.
+- Sequencing and visualization tools for radiation therapy plans.
+
+Import packages as follows:
+
+    from pyRadPlan import (
+        load_tg119,
+        PhotonPlan,
+        generate_stf,
+        calc_dose_influence,
+        fluence_optimization,
+        plot_slice,
+    )
+
+Use the documentation, docstrings or examples for a detailed overview.
+"""
 
 from importlib.metadata import version, PackageNotFoundError
 import logging

pyRadPlan/analysis/__init__.py

@@ -1,4 +1,4 @@
-"""Analysis module for pyRadPlan."""
+"""Treatment plan analysis tools and metrics."""
 
 from ._dvh import DVH, DVHCollection
 

pyRadPlan/core/__init__.py

@@ -1,4 +1,4 @@
-"""Core module with fundamental classes and functions for pyRadPlan."""
+"""Core classes and functions for pyRadPlan."""
 
 from ._exceptions import PyRadPlanError
 from .datamodel import PyRadPlanBaseModel

pyRadPlan/cst/__init__.py

@@ -1,3 +1,5 @@
+"""Clinical structures and volumes of interest."""
+
 from ._voi import VOI, OAR, Target, HelperVOI, ExternalVOI, create_voi, validate_voi
 from ._cst import StructureSet, create_cst, validate_cst
 

pyRadPlan/ct/__init__.py

@@ -1,3 +1,5 @@
+"""CT image processing and validation."""
+
 from ._ct import CT, create_ct, validate_ct, ct_from_file, resample_ct
 from ._hlut import default_hlut
 

pyRadPlan/dij/__init__.py

@@ -1,4 +1,4 @@
-"""Module for Dij Datamodel and related functions."""
+"""Dose influence matrix calculations and data structures."""
 
 from pyRadPlan.dij._dij import Dij, create_dij, validate_dij
 from pyRadPlan.dij._compose_beam_dijs import compose_beam_dijs

pyRadPlan/dose/__init__.py

@@ -1,4 +1,4 @@
-"""Provide methods for calculation dose."""
+"""Dose calculation methods and algorithms."""
 
 from ._calc_dose import calc_dose_influence, calc_dose_forward
 

pyRadPlan/dose/engines/__init__.py

@@ -1,3 +1,5 @@
+"""Dose calculation engines and algorithms."""
+
 from ._base import DoseEngineBase
 from ._svdpb import PhotonPencilBeamSVDEngine
 from ._hongpb import ParticleHongPencilBeamEngine

pyRadPlan/dose/engines/_factory.py

@@ -61,7 +61,7 @@ def get_available_engines(pln: Union[Plan, dict[str]]) -> dict[str, Type[DoseEng
 
 def get_engine(pln: Union[Plan, dict]) -> DoseEngineBase:
     """
-    Factory function to get the appropriate engine based on the plan.
+    Get the appropriate engine based on the plan.
 
     Parameters
     ----------

pyRadPlan/dose/engines/_svdpb.py

@@ -1,9 +1,3 @@
-"""
-Implementation of a pencil beam dose calculation engine for photon beams
-based on the Singular-value
-decomposition (SVD) method by Bortfeld.
-"""
-
 from typing import TypedDict, Literal, Any, cast, Callable
 import logging
 import random