docs: Fix documentation (#409)

.gitignore

@@ -70,6 +70,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/autoapi/
 warnings.txt
 
 # PyBuilder
@@ -95,6 +96,9 @@ ipython_config.py
 #   install all needed dependencies.
 #Pipfile.lock
 
+# uv
+uv.lock
+
 # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
 __pypackages__/
 
@@ -141,6 +145,9 @@ cython_debug/
 # vscode config
 .vscode/
 
+# JetBrains config
+.idea/
+
 # sandbox Notebook
 sandbox.ipynb
 test.ipynb

docs/setup/pattern.rst

@@ -35,14 +35,14 @@ Here’s how we use these decorators to write a custom “geetools” accessor i
     @register_class_accessor(ee.Number, "geetools")
     class NumberAccessor:
 
-    def __init__(self, obj: ee.Number):
-        self._obj = obj
-
-    def truncate(self, nbDecimals = 2):
-        """Truncate a number to a given number of decimals."""
-        nbDecimals = ee.Number(nbDecimals).toInt()
-        factor = ee.Number(10).pow(nbDecimals)
-        return self._obj.multiply(factor).toInt().divide(factor)
+        def __init__(self, obj: ee.Number):
+            self._obj = obj
+
+        def truncate(self, nbDecimals = 2):
+            """Truncate a number to a given number of decimals."""
+            nbDecimals = ee.Number(nbDecimals).toInt()
+            factor = ee.Number(10).pow(nbDecimals)
+            return self._obj.multiply(factor).toInt().divide(factor)
 
 In general, the only restriction on the accessor class is that the ``__init__`` method must have a single parameter: the object it is supposed to work on.
 

geetools/accessors.py

@@ -14,7 +14,7 @@ def register_class_accessor(klass: type, name: str) -> Callable:
         name: The name of the accessor namespace
 
     Returns:
-        The accessor function to to the class.
+        The accessor function to the class.
     """
 
     def decorator(accessor: Callable) -> object:
@@ -37,15 +37,15 @@ def __get__(self, obj: object, *args) -> object:
     return decorator
 
 
-def register_function_accessor(func: type, name: str) -> Callable:
-    """Add a Accessor class to function through the provided namespace.
+def register_function_accessor(func: Callable, name: str) -> Callable:
+    """Add an Accessor class to function through the provided namespace.
 
     Parameters:
         func: The function to set the accessor to.
         name: The name of the accessor namespace.
 
     Returns:
-        The accessor function to to the function.
+        The accessor function to the function.
     """
 
     def decorator(accessor: Callable) -> object:

geetools/ee_array.py

@@ -1,4 +1,4 @@
-"""Extra methods for the ``ee.Array`` class."""
+"""Extra methods for the :py:class:`ee.Array` class."""
 from __future__ import annotations
 
 import ee
@@ -8,7 +8,7 @@
 
 @register_class_accessor(ee.Array, "geetools")
 class ArrayAccessor:
-    """Toolbox for the ``ee.Array`` class."""
+    """Toolbox for the :py:class:`ee.Array` class."""
 
     def __init__(self, obj: ee.Array):
         """Initialize the Array class."""

geetools/ee_asset.py

@@ -110,7 +110,7 @@ def as_posix(self) -> str:
         return self._path.as_posix()
 
     def as_uri(self) -> str:
-        """Return the asset id as a uri.
+        """Return the asset id as an uri.
 
         The uri can be directly copy/pasted to your browser to see the asset in the GEE code editor.
 
@@ -126,7 +126,7 @@ def is_absolute(self, raised: bool = False) -> bool:
         """Return True if the asset is absolute.
 
         An absolute asset path starts with "projects" and contains "assets" at the 3rd position.
-        We don't check if the project name exist in this method, simply the sctructure of the path.
+        We don't check if the project name exist in this method, simply the structure of the path.
 
         Args:
             raised: If True, raise an exception if the asset is not absolute. Defaults to False.
@@ -495,7 +495,7 @@ def mkdir(self, parents=False, exist_ok=False, image_collection: bool = False) -
         Args:
             parents: If True, create all the parents of the folder. Defaults to False.
             exist_ok: If True, do not raise an error if the folder already exists. Defaults to False.
-            image_collection: If True, create an image collection asset. Otherwise create a folder asset. Defaults to False.
+            image_collection: If True, create an image collection asset. Otherwise, create a folder asset. Defaults to False.
 
         Examples:
             .. code-block:: python
@@ -579,7 +579,7 @@ def move(self, new_asset: Asset, overwrite: bool = False) -> Asset:
     def delete(self, recursive: bool = False, dry_run: bool | None = None) -> list:
         """Remove the asset.
 
-        This method will delete an asset (any type) asset and all its potential children. by default it is not recursive and will raise an error if the container is not empty.
+        This method will delete an asset (any type) asset and all its potential children. By default, it is not recursive and will raise an error if the container is not empty.
         By setting the recursive argument to True, the method will delete all the children and the container asset (including potential subfolders).
         To avoid deleting important assets by accident the method is set to dry_run by default.
 

geetools/ee_authenticate.py

@@ -1,4 +1,4 @@
-"""Toolbox for the ``ee.Authenticate`` function."""
+"""Toolbox for the :py:func:`ee.Authenticate` function."""
 from __future__ import annotations
 
 from contextlib import suppress
@@ -13,13 +13,13 @@
 
 @register_function_accessor(ee.Authenticate, "geetools")
 class AuthenticateAccessor:
-    """Create an accessor for the ``ee.Authenticate`` function."""
+    """Create an accessor for the :py:func:`ee.Authenticate` function."""
 
     @staticmethod
     def new_user(name: str = "", credential_pathname: str = "") -> None:
         """Authenticate the user and save the credentials in a specific folder.
 
-        Equivalent to ee.Authenticate but where the registered user will not be the default one (the one you get when running :py:meth:`ee.Initialize`)
+        Equivalent to :py:func:`ee.Authenticate` but where the registered user will not be the default one (the one you get when running :py:func:`ee.Initialize`)
 
         Args:
             name: The name of the user. If not set, it will reauthenticate default.
@@ -80,7 +80,7 @@ def delete_user(name: str = "", credential_pathname: str = "") -> None:
             (credential_path / name).unlink()
 
     @staticmethod
-    def list_user(credential_pathname: str = "") -> list:
+    def list_user(credential_pathname: str = "") -> list[str]:
         """return all the available users in the set folder.
 
         To reach "default" simply omit the ``name`` parameter in the User methods

geetools/ee_computed_object.py

@@ -1,4 +1,4 @@
-"""Extra tools for the ``ee.ComputedObject`` class."""
+"""Extra tools for the :py:class:`ee.ComputedObject` class."""
 from __future__ import annotations
 
 import json
@@ -45,9 +45,9 @@ def isInstance(self, klass: type) -> ee.Number:
 # -- .gee files ----------------------------------------------------------------
 @_register_extention(ee.ComputedObject)  # type: ignore
 def save(self, path: os.PathLike) -> Path:
-    """Save a ``ComputedObject`` to a .gee file.
+    """Save a :py:class:`ee.ComputedObject` to a .gee file.
 
-    The file contains the JSON representation of the object. it still need to be computed via ``getInfo()`` to be used.
+    The file contains the JSON representation of the object. It still needs to be computed via :py:meth:`ee.ComputedObject.getInfo` to be used.
 
     Parameters:
         path: The path to save the object to.

geetools/ee_date.py

@@ -1,4 +1,4 @@
-"""Extra methods for the ``ee.Date`` class."""
+"""Extra methods for the :py:class:`ee.Date` class."""
 from __future__ import annotations
 
 from datetime import datetime
@@ -12,7 +12,7 @@
 
 @register_class_accessor(ee.Date, "geetools")
 class DateAccessor:
-    """Toolbox for the ``ee.Date`` class."""
+    """Toolbox for the :py:class:`ee.Date` class."""
 
     def __init__(self, obj: ee.Date):
         """Initialize the Date class."""
@@ -27,7 +27,7 @@ def fromEpoch(cls, number: int, unit: str = "day") -> ee.Date:
             unit: The unit to return the number of. One of: ``second``, ``minute``, ``hour``, ``day``, ``month``, ``year``.
 
         Returns:
-            The date as a ``ee.Date`` object.
+            The date as a :py:class:`ee.Date` object.
 
         Examples:
             .. jupyter-execute::
@@ -52,7 +52,7 @@ def fromDOY(cls, doy: int, year: int) -> ee.Date:
             year: The year.
 
         Returns:
-            The date as a ``ee.Date`` object.
+            The date as a :py:class:`ee.Date` object.
 
         Examples:
             .. jupyter-execute::
@@ -89,10 +89,10 @@ def now(cls) -> ee.Date:
         return ee.Date(datetime.now().isoformat())
 
     def to_datetime(self) -> datetime:
-        """Convert a ``ee.Date`` to a ``datetime.datetime``.
+        """Convert a :py:class:`ee.Date` to a :py:class:`datetime.datetime`.
 
         Returns:
-            The ``datetime.datetime`` representation of the ``ee.Date``.
+            The :py:class:`datetime.datetime` representation of the :py:class:`ee.Date`.
 
         Examples:
             .. jupyter-execute::

geetools/ee_date_range.py

@@ -1,4 +1,4 @@
-"""Extra tools for the ``ee.DateRange`` class."""
+"""Extra tools for the :py:class:`ee.DateRange` class."""
 from __future__ import annotations
 
 import ee
@@ -8,15 +8,15 @@
 
 @register_class_accessor(ee.DateRange, "geetools")
 class DateRangeAccessor:
-    """Toolbox for the ``ee.DateRange`` class."""
+    """Toolbox for the :py:class:`ee.DateRange` class."""
 
     def __init__(self, obj: ee.DateRange):
         """Initialize the DateRange class."""
         self._obj = obj
 
     # -- date range operations -------------------------------------------------
     def split(self, interval: int | ee.Number, unit: str = "day") -> ee.List:
-        """Convert a ``ee.DateRange`` to a list of ``ee.DateRange``.
+        """Convert a :py:class:`ee.DateRange` to a list of :py:class:`ee.DateRange`.
 
         The DateRange will be split in multiple DateRanges of the specified interval and Unit.
         For example "1", "day". if the end date is not included the last dateRange length will be adapted.

geetools/ee_dictionary.py

@@ -1,4 +1,4 @@
-"""Extra methods for the ``ee.Dictionary`` class."""
+"""Extra methods for the :py:class:`ee.Dictionary` class."""
 from __future__ import annotations
 
 import ee
@@ -8,18 +8,18 @@
 
 @register_class_accessor(ee.Dictionary, "geetools")
 class DictionaryAccessor:
-    """Toolbox for the ``ee.Dictionary`` class."""
+    """Toolbox for the :py:class:`ee.Dictionary` class."""
 
     def __init__(self, obj: ee.Dictionary):
         """Initialize the Dictionary class."""
         self._obj = obj
 
     # -- alternative constructor -----------------------------------------------
     def fromPairs(self, list: list | ee.List) -> ee.Dictionary:
-        """Create a dictionary from a list of [[key, value], ...]] pairs.
+        """Create a dictionary from a list of ``[[key, value], ...]]`` pairs.
 
         Parameters:
-            list: A list of pairs (key, value).
+            list: A list of pairs ``(key, value)``.
 
         Returns:
             A dictionary using the pairs.

geetools/ee_export.py

@@ -9,7 +9,7 @@
 
 @register_class_accessor(ee.batch.Export, "geetools")
 class ExportAccessor:
-    """Toolbox for the ``ee.batch.Export`` class."""
+    """Toolbox for the :py:class:`ee.batch.Export` class."""
 
     def __init__(self, obj: ee.batch.Export):
         """Initialize the ExportAccessor class."""
@@ -41,10 +41,10 @@ def toAsset(
 
             Parameters:
                 imagecollection: The image collection to export.
-                index_property: The property of the image to use as name. Default is "system:id".
+                index_property: The property of the image to use as name. Default is ``"system:id"``.
                 description: The description of the task.
                 assetId: The asset id where to export the image collection.
-                **kwargs: every parameter that you would use for a vanilla ee.batch.Export.image.toAsset
+                **kwargs: every parameter that you would use for a vanilla :py:meth:`ee.batch.Export.image.toAsset`
 
             Returns:
                 The task created.
@@ -62,7 +62,6 @@ def toAsset(
 
                     # export the collection
                     tasks = geetools.batch.Export.imagecollection.toAsset(collection, "system:index", "test export")
-                ```
             """
             # sanity check on parameters
             # renaming them for mypy type reassignment and compactness
@@ -108,10 +107,10 @@ def toDrive(
 
             Parameters:
                 imagecollection: The image collection to export.
-                index_property: The property of the image to use as name. Default is "system:id".
+                index_property: The property of the image to use as name. Default is ``"system:id"``.
                 description: The description of the task.
                 folder: The folder id where to export the image collection. It will be stored at the root of the drive.
-                **kwargs: every parameter that you would use for a vanilla ee.batch.Export.image.toDrive
+                **kwargs: every parameter that you would use for a vanilla :py:meth:`ee.batch.Export.image.toDrive`
 
             Returns:
                 The list of created tasks
@@ -172,10 +171,10 @@ def toCloudStorage(
 
             Parameters:
                 imagecollection: The image collection to export.
-                index_property: The property of the image to use as name. Default is "system:id".
+                index_property: The property of the image to use as name. Default is ``"system:id"``.
                 description: The description of the task.
                 folder: The folder id where to export the image collection. It will be stored at the root of the drive.
-                **kwargs: every parameter that you would use for a vanilla ee.batch.Export.image.toCloudStorage
+                **kwargs: every parameter that you would use for a vanilla :py:meth:`ee.batch.Export.image.toCloudStorage`
 
             Returns:
                 The list of created tasks

geetools/ee_feature.py

@@ -1,4 +1,4 @@
-"""Toolbox for the ``ee.Feature`` class."""
+"""Toolbox for the :py:class:`ee.Feature` class."""
 from __future__ import annotations
 
 import ee
@@ -8,7 +8,7 @@
 
 @register_class_accessor(ee.Feature, "geetools")
 class FeatureAccessor:
-    """Toolbox for the ``ee.Feature`` class."""
+    """Toolbox for the :py:class:`ee.Feature` class."""
 
     def __init__(self, obj: ee.Feature):
         """Initialize the class."""
@@ -18,7 +18,7 @@ def toFeatureCollection(self) -> ee.FeatureCollection:
         """Convert a :py:class:`ee.Feature` composed of a multiGeometry geometry into a :py:class:`ee.FeatureCollection`.
 
         Returns:
-            The FeatureCollection
+            The :py:class:`ee.FeatureCollection`
 
         Example:
             .. jupyter-execute::