[WIP] Issue #390 add openeo.processes docs

Author: soxofaan

docs/api-processes.rst

@@ -0,0 +1,20 @@
+==========================
+API: ``openeo.processes``
+==========================
+
+The ``openeo.processes`` module contains helper to build call
+
+
+``openeo.processes`` functions
+-------------------------------
+
+.. automodule:: openeo.processes
+    :members:
+    :exclude-members: ProcessBuilder
+
+
+``openeo.processes.ProcessBuilder``
+------------------------------------
+
+.. automodule:: openeo.processes
+    :members: ProcessBuilder

docs/api.rst

@@ -1,6 +1,6 @@
-===
-API
-===
+=============
+API: General
+=============
 
 High level Interface
 --------------------

docs/index.rst

@@ -60,6 +60,7 @@ Table of contents
    configuration
    cookbook/index
    api
+   api-processes
    process_mapping
    development
    best_practices

docs/process_mapping.py

@@ -39,6 +39,11 @@ def main():
                 - openEO Python Client Method
     """))
 
+    import openeo.rest.datacube
+    import openeo.rest.vectorcube
+    import openeo.rest.mlmodel
+    import openeo.processes
+
     for process_id in sorted(_process_registry.keys()):
         functions = [x[0] for x in _process_registry[process_id]]
         refs = [

docs/process_mapping.rst

@@ -6,6 +6,7 @@
 from functools import partial
 from typing import Callable, Optional
 
+
 # TODO: give this a proper public API?
 _process_registry = collections.defaultdict(list)
 

openeo/internal/documentation.py

@@ -3,7 +3,7 @@
 import sys
 import textwrap
 from pathlib import Path
-from typing import Union, List, Iterator
+from typing import Union, List, Iterator, Optional
 
 from openeo.internal.processes.parse import Process, parse_all_from_dir
 
@@ -13,18 +13,20 @@ class PythonRenderer:
     DEFAULT_WIDTH = 115
 
     def __init__(
-            self,
-            oo_mode=False,
-            indent="    ",
-            body_template="return _process({id!r}, {args})",
-            optional_default="None",
-            return_type_hint: str = None
+        self,
+        oo_mode: bool = False,
+        indent: str = "    ",
+        body_template: str = "return _process({id!r}, {args})",
+        optional_default="None",
+        return_type_hint: Optional[str] = None,
+        decorator: Optional[str] = None,
     ):
         self.oo_mode = oo_mode
         self.indent = indent
         self.body_template = body_template
         self.optional_default = optional_default
         self.return_type_hint = return_type_hint
+        self.decorator = decorator
 
     def render_process(self, process: Process, prefix: str = None, width: int = DEFAULT_WIDTH) -> str:
         if prefix is None:
@@ -45,11 +47,12 @@ def render_process(self, process: Process, prefix: str = None, width: int = DEFA
             id=process.id, safe_name=self._safe_name(process.id), args=call_args
         )
 
-        return textwrap.indent("\n".join([
+        lines = ([self.decorator] if self.decorator else []) + [
             def_line,
             self.render_docstring(process, width=width - len(prefix), prefix=self.indent),
             body
-        ]), prefix=prefix)
+        ]
+        return textwrap.indent("\n".join(lines), prefix=prefix)
 
     def _safe_name(self, name: str) -> str:
         if keyword.iskeyword(name):
@@ -106,45 +109,58 @@ def collect_processes(sources: List[Union[Path, str]]) -> List[Process]:
 
 
 def generate_process_py(processes: List[Process], output=sys.stdout, argv=None):
-    oo_src = textwrap.dedent("""
+    oo_src = textwrap.dedent(
+        """
         import builtins
         from openeo.internal.processes.builder import ProcessBuilderBase, UNSET
+        from openeo.internal.documentation import openeo_process
 
 
         class ProcessBuilder(ProcessBuilderBase):
 
             _ITERATION_LIMIT = 100
 
+            @openeo_process(process_id="add", mode="operator")
             def __add__(self, other) -> 'ProcessBuilder':
                 return self.add(other)
 
+            @openeo_process(process_id="add", mode="operator")
             def __radd__(self, other) -> 'ProcessBuilder':
                 return add(other, self)
 
+            @openeo_process(process_id="subtract", mode="operator")
             def __sub__(self, other) -> 'ProcessBuilder':
                 return self.subtract(other)
 
+            @openeo_process(process_id="subtract", mode="operator")
             def __rsub__(self, other) -> 'ProcessBuilder':
                 return subtract(other, self)
 
+            @openeo_process(process_id="multiply", mode="operator")
             def __mul__(self, other) -> 'ProcessBuilder':
                 return self.multiply(other)
 
+            @openeo_process(process_id="multiply", mode="operator")
             def __rmul__(self, other) -> 'ProcessBuilder':
                 return multiply(other, self)
 
+            @openeo_process(process_id="divide", mode="operator")
             def __truediv__(self, other) -> 'ProcessBuilder':
                 return self.divide(other)
 
+            @openeo_process(process_id="divide", mode="operator")
             def __rtruediv__(self, other) -> 'ProcessBuilder':
                 return divide(other, self)
 
+            @openeo_process(process_id="multiply", mode="operator")
             def __neg__(self) -> 'ProcessBuilder':
                 return self.multiply(-1)
 
+            @openeo_process(process_id="power", mode="operator")
             def __pow__(self, other) -> 'ProcessBuilder':
                 return self.power(other)
 
+            @openeo_process(process_id="array_element", mode="operator")
             def __getitem__(self, key) -> 'ProcessBuilder':
                 if isinstance(key, builtins.int):
                     if key > self._ITERATION_LIMIT:
@@ -157,43 +173,54 @@ def __getitem__(self, key) -> 'ProcessBuilder':
                 else:
                     return self.array_element(label=key)
 
+            @openeo_process(process_id="eq", mode="operator")
             def __eq__(self, other) -> 'ProcessBuilder':
                 return eq(self, other)
 
+            @openeo_process(process_id="neq", mode="operator")
             def __ne__(self, other) -> 'ProcessBuilder':
                 return neq(self, other)
 
+            @openeo_process(process_id="lt", mode="operator")
             def __lt__(self, other) -> 'ProcessBuilder':
                 return lt(self, other)
 
+            @openeo_process(process_id="lte", mode="operator")
             def __le__(self, other) -> 'ProcessBuilder':
                 return lte(self, other)
 
+            @openeo_process(process_id="ge", mode="operator")
             def __ge__(self, other) -> 'ProcessBuilder':
                 return gte(self, other)
 
+            @openeo_process(process_id="gt", mode="operator")
             def __gt__(self, other) -> 'ProcessBuilder':
                 return gt(self, other)
 
-    """)
-    fun_src = textwrap.dedent("""
+    """
+    )
+    fun_src = textwrap.dedent(
+        """
         # Public shortcut
         process = ProcessBuilder.process
         # Private shortcut that has lower chance to collide with a process argument named `process`
         _process = ProcessBuilder.process
 
 
-    """)
+    """
+    )
     fun_renderer = PythonRenderer(
         body_template="return _process({id!r}, {args})",
         optional_default="UNSET",
-        return_type_hint="ProcessBuilder"
+        return_type_hint="ProcessBuilder",
+        decorator="@openeo_process",
     )
     oo_renderer = PythonRenderer(
         oo_mode=True,
         body_template="return {safe_name}({args})",
         optional_default="UNSET",
-        return_type_hint="'ProcessBuilder'"
+        return_type_hint="'ProcessBuilder'",
+        decorator="@openeo_process",
     )
     for p in processes:
         fun_src += fun_renderer.render_process(p) + "\n\n\n"