Update documentation to discuss sum of profiles (#275)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

docs/source/api/profiles/index.rst

@@ -1,6 +1,9 @@
 Laser Profiles
 ==============
 
+.. autoclass:: lasy.profiles.Profile
+    :members:
+
 .. toctree::
    :hidden:
 

docs/source/api/profiles/transverse/index.rst

@@ -1,6 +1,9 @@
 Transverse Laser Profiles
 =========================
 
+.. autoclass:: lasy.profiles.transverse.TransverseProfile
+    :members:
+
 .. toctree::
    :maxdepth: 4
    :hidden:

lasy/profiles/__init__.py

@@ -3,9 +3,11 @@
 from .from_insight_file import FromInsightFile
 from .from_openpmd_profile import FromOpenPMDProfile
 from .gaussian_profile import GaussianProfile
+from .profile import Profile
 from .speckle_profile import SpeckleProfile
 
 __all__ = [
+    "Profile",
     "CombinedLongitudinalTransverseProfile",
     "GaussianProfile",
     "FromArrayProfile",

lasy/profiles/profile.py

@@ -8,6 +8,11 @@ class Profile(object):
 
     Any new laser profile should inherit from this class, and define its own
     `evaluate` method, using the same signature as the method below.
+    For most cases, use derived classes instead of this base class.
+
+    Common operators (addition and multiplication by a scalar) are provided as part of this base class.
+    For such operations, the user is responsible for handling the complex phase and weights of summed profiles.
+    In particular, summing between different types of profiles is not recommended.
 
     Parameters
     ----------

lasy/profiles/transverse/transverse_profile.py

@@ -7,6 +7,12 @@ class TransverseProfile(object):
 
     Any new transverse profile should inherit from this class, and define its own
     `evaluate` method, using the same signature as the method below.
+    For most cases, use derived classes instead of this base class.
+
+    Common operators (addition and multiplication by a scalar) are provided as part of this base class.
+    For such operations, the user is responsible for handling the complex phase and weights of summed profiles.
+    In particular, summing between different types of profiles is not recommended.
+    This feature is tailored for linear combination of profiles of the same type, in particular analytical profiles like Laguerre-gauss or Hermite-Gauss.
     """
 
     def __init__(self):