docs: restore assets in the documentation

docs/_extension/docstring.py

@@ -1,12 +1,16 @@
 """A docstring role to read the docstring from a Python method."""
 from __future__ import annotations
 
+import inspect
+from functools import reduce
+
+import ee
 from docutils import nodes
 from sphinx.application import Sphinx
 from sphinx.util import logging
 from sphinx.util.docutils import SphinxRole
 
-import geetools
+import geetools  # noqa: F401
 
 logger = logging.getLogger(__name__)
 
@@ -16,11 +20,33 @@ class DocstringRole(SphinxRole):
 
     def run(self) -> tuple[list[nodes.Node], list[str]]:
         """Setup the role in the builder context."""
+        # retrieve the environment from the node members
+        env = self.inliner.document.settings.env
+        builder = env.app.builder
+        current_doc = self.env.docname
+
+        # extract the members we try to reach from the ee lib
         members = self.text.split(".")[1:]
-        o = geetools
-        [o := getattr(o, m) for m in members]
 
-        return [nodes.Text(o.__doc__.splitlines()[0])], []
+        # reach the final object using getattr. It will allow us to access the complete information
+        #  of the object (docstring, qualname, name, source module)
+        try:
+            o = reduce(getattr, members, ee)
+            modules = inspect.getmodule(o).__name__.split(".")
+        except Exception as e:
+            logger.warning(f"Failed to retrieve {members}: {e}")
+            return [nodes.Text(f"{self.text} not found")], []
+
+        # create the docstring node
+        docstring = nodes.Text(f": {o.__doc__.splitlines()[0]}")
+
+        # create a complete link to the object using the url and the name of the object
+        target_doc = f"autoapi/{'/'.join(modules)}/{o.__qualname__}"
+        refuri = builder.get_relative_uri(current_doc, target_doc)
+        inline_node = nodes.literal(self.text, self.text, classes=["py", "py-meth"])
+        link = nodes.reference("", "", inline_node, internal=True, refuri=refuri)
+
+        return [link, docstring], []
 
 
 def setup(app: Sphinx) -> dict[str, object]:

docs/conf.py

@@ -116,6 +116,7 @@
     "special-members",
 ]
 autoapi_own_page_level = "method"
+autoapi_keep_files = False
 
 # -- Options for intersphinx output --------------------------------------------
 intersphinx_mapping = {}

docs/usage/asset.ipynb

@@ -251,8 +251,8 @@
    "metadata": {},
    "source": [
     "```{api}\n",
-    "- {py:meth}`iterdir <geetools.Asset.Asset.iterdir>`: {docstring}`geetools.Asset.iterdir`\n",
-    "- {py:meth}`is_folder <geetools.Asset.Asset.is_folder>`: {docstring}`geetools.Asset.is_folder`\n",
+    "- {docstring}`ee.Asset.iterdir`\n",
+    "- {{docstring}`ee.Asset.is_folder`\n",
     "```"
    ]
   },
@@ -316,9 +316,9 @@
    "metadata": {},
    "source": [
     "```{api}\n",
-    "- {py:meth}`iterdir <geetools.Asset.Asset.iterdir>`: {docstring}`geetools.Asset.iterdir`\n",
-    "- {py:meth}`glob <geetools.Asset.Asset.glob>`: {docstring}`geetools.Asset.glob`\n",
-    "- {py:meth}`is_image <geetools.Asset.Asset.is_image>`: {docstring}`geetools.Asset.is_image`\n",
+    "- {docstring}`ee.Asset.iterdir`\n",
+    "- {docstring}`ee.Asset.glob`\n",
+    "- {docstring}`ee.Asset.is_image`\n",
     "```"
    ]
   },
@@ -375,7 +375,7 @@
    "metadata": {},
    "source": [
     "```{api}\n",
-    "- {py:meth}`exists <geetools.Asset.Asset.exists>`: {docstring}`geetools.Asset.exists`\n",
+    "- {docstring}`ee.Asset.exists`\n",
     "```"
    ]
   },
@@ -557,7 +557,7 @@
    "metadata": {},
    "source": [
     "```{api}\n",
-    "- {py:meth}`parts <geetools.Asset.Asset.parts>`: {docstring}`geetools.Asset.parts`\n",
+    "- {docstring}`ee.Asset.parts`\n",
     "```"
    ]
   },
@@ -570,8 +570,8 @@
     "Asset parent containers can be access either by the `parent` property or the `parents` property. Note This is a purely lexical operation and the parent is not checked to exist.\n",
     "\n",
     "```{api}\n",
-    "- {py:meth}`parent <geetools.Asset.Asset.parent>`: {docstring}`geetools.Asset.parent`\n",
-    "- {py:meth}`parents <geetools.Asset.Asset.parents>`: {docstring}`geetools.Asset.parents`\n",
+    "- {docstring}`ee.Asset.parent`\n",
+    "- {docstring}`ee.Asset.parents`\n",
     "```"
    ]
   },
@@ -627,7 +627,7 @@
     "A string representing the final path component can be used to get the name of the asset.add\n",
     "\n",
     "```{api}\n",
-    "- {py:meth}`name <geetools.Asset.Asset.name>`: {docstring}`geetools.Asset.name`\n",
+    "- {docstring}`ee.Asset.name`\n",
     "```"
    ]
   },
@@ -670,7 +670,7 @@
     "It's possible to check if files are related between one another using the following methods:\n",
     "\n",
     "```{api}\n",
-    "- {py:meth}`is_relative_to <geetools.Asset.Asset.is_relative_to>`: {docstring}`geetools.Asset.is_relative_to`"
+    "- {docstring}`ee.Asset.is_relative_to`"
    ]
   },
   {
@@ -704,7 +704,7 @@
     "One can create a siblings asset in the same container by using the `with_name()` method:\n",
     "\n",
     "```{api}    \n",
-    "- {py:meth}`with_name <geetools.Asset.Asset.with_name>`: {docstring}`geetools.Asset.with_name`\n",
+    "- {docstring}`ee.Asset.with_name`\n",
     "```"
    ]
   },
@@ -738,7 +738,7 @@
     "One can use some unix-like descriptors in it's Asset constructor parameters. If so before using the Asset object, it is necessary to resolve these symbols. The method `expanduser` does that.\n",
     "\n",
     "```{api}\n",
-    "- {py:meth}`expanduser <geetools.Asset.Asset.expanduser>`: {docstring}`geetools.Asset.expanduser`\n",
+    "- {py:meth}`expanduser <ee.Asset.Asset.expanduser>`: {docstring}`ee.Asset.expanduser`\n",
     "```"
    ]
   },
@@ -772,7 +772,7 @@
     "One can check if an asset exists using the `exists` method:\n",
     "\n",
     "```{api}\n",
-    "- {py:meth}`exists <geetools.Asset.Asset.exists>`: {docstring}`geetools.Asset.exists`\n",
+    "- {py:meth}`exists <ee.Asset.Asset.exists>`: {docstring}`ee.Asset.exists`\n",
     "```"
    ]
   },
@@ -827,7 +827,7 @@
     "As Earth Engine is not using any file extention to differentiate the asset type, one can use the `is_type` method with any of the following types: `IMAGE`, `IMAGE_COLLECTION`, `FOLDER`, `TABLE`, `FEATURE_COLLECTION`, `UNKNOWN`.\n",
     "\n",
     "```{api}\n",
-    "- {py:meth}`is_type <geetools.Asset.Asset.is_type>`: {docstring}`geetools.Asset.is_type`\n",
+    "- {py:meth}`is_type <ee.Asset.Asset.is_type>`: {docstring}`ee.Asset.is_type`\n",
     "```"
    ]
   },
@@ -883,7 +883,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Many other useful methods are available and are described in the {py:class}`API documentation <geetools.Asset.Asset>`."
+    "Many other useful methods are available and are described in the {py:class}`API documentation <ee.Asset.Asset>`."
    ]
   }
  ],

docs/usage/plot/map-featurecollection.ipynb

@@ -106,7 +106,7 @@
     "## Map Vector\n",
     "\n",
     "```{api}\n",
-    "{py:meth}`plot <geetools.FeatureCollection.FeatureCollectionAccessor.plot>`: {docstring}`geetools.FeatureCollectionAccessor.plot`\n",
+    "{docstring}`ee.FeatureCollection.geetools.plot`\n",
     "```\n",
     "\n",
     "An `ee.FeatureCollection` is a vector representation of geographical properties. A user can be interested by either the property evolution across the landscape or the geometries associated with it. The {py:meth}`plot <geetools.FeatureCollection.FeatureCollectionAccessor.plot>` is coverinig both use cases. \n",

docs/usage/plot/plot-featurecollection.ipynb

@@ -177,8 +177,8 @@
    "metadata": {},
    "source": [
     "```{api}\n",
-    "- {py:meth}`plot_by_features <geetools.FeatureCollection.FeatureCollectionAccessor.plot_by_features>`: {docstring}`geetools.FeatureCollectionAccessor.plot_by_features`\n",
-    "- {py:meth}`byFeatures <geetools.FeatureCollection.FeatureCollectionAccessor.byFeatures>`: {docstring}`geetools.FeatureCollectionAccessor.byFeatures`\n",
+    "- {docstring}`geetools.FeatureCollectionAccessor.plot_by_features`\n",
+    "- {docstring}`ee.FeatureCollection.geetools.byFeatures`\n",
     "```"
    ]
   },
@@ -477,8 +477,8 @@
    "metadata": {},
    "source": [
     "```{api}\n",
-    "{py:meth}`plot_by_properties <geetools.FeatureCollection.FeatureCollectionAccessor.plot_by_properties>`: {docstring}`geetools.FeatureCollectionAccessor.plot_by_properties`\n",
-    "{py:meth}`byProperties <geetools.FeatureCollection.FeatureCollectionAccessor.byProperties>`: {docstring}`geetools.FeatureCollectionAccessor.byProperties`\n",
+    "- {docstring}`ee.FeatureCollection.geetools.plot_by_properties`\n",
+    "- {docstring}`ee.FeatureCollection.geetools.byProperties`\n",
     "```"
    ]
   },
@@ -625,7 +625,7 @@
     "## Plot hist\n",
     "\n",
     "```{api}\n",
-    "{py:meth}`plot_hist <geetools.FeatureCollection.FeatureCollectionAccessor.plot_hist>`: {docstring}`geetools.FeatureCollectionAccessor.plot_hist`\n",
+    "{docstring}`ee.FeatureCollection.geetools.plot_hist`\n",
     "```\n",
     "\n",
     "The x-axis is defined by value bins for the range of values of a selected property; the y-axis is the number of elements in the given bin."

docs/usage/plot/plot-image.ipynb

@@ -177,8 +177,8 @@
    "metadata": {},
    "source": [
     "```{api}\n",
-    "- {py:meth}`plot_by_regions <geetools.Image.ImageAccessor.plot_by_regions>`: {docstring}`geetools.ImageAccessor.plot_by_regions`\n",
-    "- {py:meth}`byRegions <geetools.Image.ImageAccessor.byRegions>`: {docstring}`geetools.ImageAccessor.byRegions`\n",
+    "- {docstring}`ee.Image.geetools.plot_by_regions`\n",
+    "- {docstring}`ee.Image.geetools.byRegions`\n",
     "```"
    ]
   },

geetools/__init__.py

@@ -5,7 +5,7 @@
 from .accessors import geetools
 
 # it needs to be imported first as it's the mother class
-from . import ComputedObject
+from .ee_computed_object import *
 
 # reproduce older structure of the lib (deprecated)
 # will be removed along the deprecation cycle
@@ -14,24 +14,24 @@
 from .tools import imagecollection
 
 # then we extend all the other classes
-from .Asset import Asset
-from .Date import DateAccessor
-from .Dictionary import DictionaryAccessor
-from .Feature import FeatureAccessor
-from .FeatureCollection import FeatureCollectionAccessor
-from .Filter import FilterAccessor
-from .Geometry import GeometryAccessor
-from .Image import ImageAccessor
-from .Join import JoinAccessor
-from .List import ListAccessor
-from .Number import NumberAccessor
-from .String import StringAccessor
-from .ImageCollection import ImageCollectionAccessor
-from .Initialize import InitializeAccessor
-from .Authenticate import AuthenticateAccessor
-from .Array import ArrayAccessor
-from .DateRange import DateRangeAccessor
-from .Export import ExportAccessor
+from .ee_asset import Asset
+from .ee_date import DateAccessor
+from .ee_dictionary import DictionaryAccessor
+from .ee_feature import FeatureAccessor
+from .ee_feature_collection import FeatureCollectionAccessor
+from .ee_filter import FilterAccessor
+from .ee_geometry import GeometryAccessor
+from .ee_image import ImageAccessor
+from .ee_join import JoinAccessor
+from .ee_list import ListAccessor
+from .ee_number import NumberAccessor
+from .ee_string import StringAccessor
+from .ee_image_collection import ImageCollectionAccessor
+from .ee_initialize import InitializeAccessor
+from .ee_authenticate import AuthenticateAccessor
+from .ee_array import ArrayAccessor
+from .ee_date_range import DateRangeAccessor
+from .ee_export import ExportAccessor
 from .ee_profiler import Profiler
 
 __title__ = "geetools"

geetools/Asset.py → geetools/ee_asset.py

@@ -451,8 +451,8 @@ def iterdir(self, recursive: bool = False) -> list:
             recursive: If True, get all the children recursively. Defaults to False.
 
         See Also:
-            - :py:meth:`glob <geetools.Asset.Asset.glob>`: :docstring:`geetools.Asset.glob`
-            - :py:meth:`rglob <geetools.Asset.Asset.rglob>`: :docstring:`geetools.Asset.rglob`
+            - :docstring:`ee.Asset.glob`
+            - :docstring:`ee.Asset.rglob`
 
         Examples:
             .. code-block:: python
@@ -698,8 +698,8 @@ def glob(self, pattern: str) -> list:
             pattern: The pattern to match with the asset name.
 
         See Also:
-            - :py:meth:`iterdir <geetools.Asset.Asset.iterdir>`: :docstring:`geetools.Asset.iterdir`
-            - :py:meth:`glob <geetools.Asset.Asset.rglob>`: :docstring:`geetools.Asset.rglob`
+            - :docstring:`ee.Asset.iterdir`
+            - :docstring:`ee.Asset.rglob`
 
         Examples:
             .. code-block:: python
@@ -716,8 +716,8 @@ def rglob(self, pattern: str) -> list:
             pattern: The pattern to match with the asset name.
 
         See Also:
-            - :py:meth:`glob <geetools.Asset.Asset.glob>`: :docstring:`geetools.Asset.glob`
-            - :py:meth:`iterdir <geetools.Asset.Asset.iterdir>`: :docstring:`geetools.Asset.iterdir`
+            - :docstring:`ee.Asset.glob`
+            - :docstring:`ee.Asset.iterdir`
 
         Examples:
             .. code-block:: python

geetools/FeatureCollection.py → geetools/ee_feature_collection.py

@@ -154,8 +154,8 @@ def byProperties(
             A dictionary with all the properties as keys and their values in each feaure as a list.
 
         See Also:
-            - :py:meth:`byFeatures <geetools.FeatureCollection.FeatureCollectionAccessor.byFeatures>`: :docstring:`geetools.FeatureCollectionAccessor.byFeatures`
-            - :py:meth:`plot_by_properties <geetools.FeatureCollection.FeatureCollectionAccessor.plot_by_properties>`: :docstring:`geetools.FeatureCollectionAccessor.plot_by_properties`
+            - :docstring:`ee.FeatureCollection.geetools.byFeatures`
+            - :docstring:`ee.FeatureCollection.geetools.plot_by_properties`
 
         Example:
             .. code-block:: python
@@ -213,8 +213,8 @@ def byFeatures(
             A dictionary with all the feature ids as keys and their properties as a dictionary.
 
         See Also:
-            - :py:meth:`byProperties <geetools.FeatureCollection.FeatureCollectionAccessor.byProperties>`: :docstring:`geetools.FeatureCollectionAccessor.byProperties`
-            - :py:meth:`plot_by_features <geetools.FeatureCollection.FeatureCollectionAccessor.plot_by_features>`: :docstring:`geetools.FeatureCollectionAccessor.plot_by_features`
+            - :docstring:`ee.FeatureCollection.geetools.byProperties`
+            - :docstring:`ee.FeatureCollection.geetools.plot_by_features`
 
         Examples:
             .. code-block:: python
@@ -274,10 +274,10 @@ def plot_by_features(
             kwargs: Additional arguments from the ``pyplot`` function.
 
         See Also:
-            - :py:meth:`byFeatures <geetools.FeatureCollection.FeatureCollectionAccessor.byFeatures>`: :docstring:`geetools.FeatureCollectionAccessor.byFeatures`
-            - :py:meth:`plot_by_properties <geetools.FeatureCollection.FeatureCollectionAccessor.plot_by_properties>`: :docstring:`geetools.FeatureCollectionAccessor.plot_by_properties`
-            - :py:meth:`plot_hist <geetools.FeatureCollection.FeatureCollectionAccessor.plot_hist>`: :docstring:`geetools.FeatureCollectionAccessor.plot_hist`
-            - :py:meth:`plot <geetools.FeatureCollection.FeatureCollectionAccessor.plot>`: :docstring:`geetools.FeatureCollectionAccessor.plot`
+            - :docstring:`ee.FeatureCollection.geetools.byFeatures`
+            - :docstring:`ee.FeatureCollection.geetools.plot_by_properties`
+            - :docstring:`ee.FeatureCollection.geetools.plot_hist`
+            - :docstring:`ee.FeatureCollection.geetools.plot`
 
         Examples:
             .. code-block:: python
@@ -327,10 +327,10 @@ def plot_by_properties(
             kwargs: Additional arguments from the ``pyplot`` function.
 
         See Also:
-            - :py:meth:`byProperties <geetools.FeatureCollection.FeatureCollectionAccessor.byProperties>`: :docstring:`geetools.FeatureCollectionAccessor.byProperties`
-            - :py:meth:`plot_by_features <geetools.FeatureCollection.FeatureCollectionAccessor.plot_by_features>`: :docstring:`geetools.FeatureCollectionAccessor.plot_by_features`
-            - :py:meth:`plot_hist <geetools.FeatureCollection.FeatureCollectionAccessor.plot_hist>`: :docstring:`geetools.FeatureCollectionAccessor.plot_hist`
-            - :py:meth:`plot <geetools.FeatureCollection.FeatureCollectionAccessor.plot>`: :docstring:`geetools.FeatureCollectionAccessor.plot`
+            - :docstring:`ee.FeatureCollection.geetools.byProperties`
+            - :docstring:`ee.FeatureCollection.geetools.plot_by_features`
+            - :docstring:`ee.FeatureCollection.geetools.plot_hist`
+            - :docstring:`ee.FeatureCollection.geetools.plot`
 
         Examples:
             .. code-block:: python
@@ -375,9 +375,9 @@ def plot_hist(
             kwargs: Additional arguments from the ``pyplot.hist`` function.
 
         See Also:
-            - :py:meth:`plot_by_features <geetools.FeatureCollection.FeatureCollectionAccessor.plot_by_features>`: :docstring:`geetools.FeatureCollectionAccessor.plot_by_features`
-            - :py:meth:`plot_by_properties <geetools.FeatureCollection.FeatureCollectionAccessor.plot_by_properties>`: :docstring:`geetools.FeatureCollectionAccessor.plot_by_properties`
-            - :py:meth:`plot <geetools.FeatureCollection.FeatureCollectionAccessor.plot>`: :docstring:`geetools.FeatureCollectionAccessor.plot`
+            - :docstring:`ee.FeatureCollection.geetools.plot_by_features`
+            - :docstring:`ee.FeatureCollection.geetools.plot_by_properties`
+            - :docstring:`ee.FeatureCollection.geetools.plot`
 
         Examples:
             .. code-block:: python
@@ -444,9 +444,9 @@ def plot(
             color: The color to use for the boundaries.
 
         See Also:
-            - :py:meth:`plot_by_features <geetools.FeatureCollection.FeatureCollectionAccessor.plot_by_features>`: :docstring:`geetools.FeatureCollectionAccessor.plot_by_features`
-            - :py:meth:`plot_by_properties <geetools.FeatureCollection.FeatureCollectionAccessor.plot_by_properties>`: :docstring:`geetools.FeatureCollectionAccessor.plot_by_properties`
-            - :py:meth:`plot_hist <geetools.FeatureCollection.FeatureCollectionAccessor.plot_hist>`: :docstring:`geetools.FeatureCollectionAccessor.plot_hist`
+            - :docstring:`ee.FeatureCollection.geetools.plot_by_features`
+            - :docstring:`ee.FeatureCollection.geetools.plot_by_properties`
+            - :docstring:`ee.FeatureCollection.geetools.plot_hist`
 
         Examples:
             .. code-block:: python