Finetune docs on loading a DataCube from a JSON resource (e.g. UDPs)

Author: soxofaan

docs/cookbook/udp_sharing.rst

@@ -105,21 +105,29 @@ Loading a published user-defined process as DataCube
 
 From the public URL of the user-defined process,
 it is also possible for another user to construct, fully client-side,
-a new :class:`~openeo.rest.datacube.DataCube`
-with :meth:`Connection.datacube_from_json <openeo.rest.connection.Connection.datacube_from_json>`.
+a new :py:class:`~openeo.rest.datacube.DataCube`
+with :py:meth:`Connection.datacube_from_json() <openeo.rest.connection.Connection.datacube_from_json>`.
 
 It is important to note that this approach is different from calling
 a user-defined process as described in :ref:`evaluate_udp` and :ref:`udp_sharing_call_url_namespace`.
-:meth:`Connection.datacube_from_json <openeo.rest.connection.Connection.datacube_from_json>`
+:py:meth:`Connection.datacube_from_json() <openeo.rest.connection.Connection.datacube_from_json>`
 breaks open the encapsulation of the user-defined process and "unrolls" the process graph inside
-into a new :class:`~openeo.rest.datacube.DataCube`.
+into a new :py:class:`~openeo.rest.datacube.DataCube`.
 This also implies that parameters defined in the user-defined process have to be provided when calling
-:meth:`Connection.datacube_from_json <openeo.rest.connection.Connection.datacube_from_json>` ::
+:py:meth:`Connection.datacube_from_json() <openeo.rest.connection.Connection.datacube_from_json>`:
 
 
+.. code-block:: python
+    :emphasize-lines: 4
+
     udp_url = "https://openeo.vito.be/openeo/1.0/processes/u:johndoe/fahrenheit_to_celsius"
-    cube = connection.datacube_from_json(udp_url, parameters={"f": 86})
+    cube = connection.datacube_from_json(
+        udp_url,
+        parameters={"f": 86},
+    )
     print(cube.execute())
     # Prints: 30.0
 
+Note that :py:meth:`Connection.datacube_from_json() <openeo.rest.connection.Connection.datacube_from_json>`
+not only supports loading UDPs from an URL but also from a raw JSON string or a local file path.
 For more information, also see :ref:`datacube_from_json`.

docs/datacube_construction.rst

@@ -9,16 +9,16 @@ The ``load_collection`` process
 
 The most straightforward way to start building your openEO data cube is through the ``load_collection`` process.
 As mentioned earlier, this is provided by the
-:meth:`~openeo.rest.connection.Connection.load_collection` method
-on a :class:`~openeo.rest.connection.Connection` object,
-which produces a :class:`~openeo.rest.datacube.DataCube` instance.
+:py:meth:`~openeo.rest.connection.Connection.load_collection` method
+on a :py:class:`~openeo.rest.connection.Connection` object,
+which produces a :py:class:`~openeo.rest.datacube.DataCube` instance.
 For example::
 
     cube = connection.load_collection("SENTINEL2_TOC")
 
 While this should cover the majority of use cases,
 there some cases
-where one wants to build a :class:`~openeo.rest.datacube.DataCube` object
+where one wants to build a :py:class:`~openeo.rest.datacube.DataCube` object
 from something else or something more than just a simple ``load_collection`` process.
 
 
@@ -38,7 +38,7 @@ but let's assume there is a parameter "dilation" to fine-tune the cloud mask.
 Also note that the collection id "SENTINEL2_TOC" is hardcoded in the user-defined process.
 
 We can now construct a data cube from this user-defined process
-with :meth:`~openeo.rest.connection.Connection.datacube_from_process`
+with :py:meth:`~openeo.rest.connection.Connection.datacube_from_process`
 as follows::
 
     cube = connection.datacube_from_process("masked_s2", dilation=10)
@@ -47,7 +47,7 @@ as follows::
     cube = cube.filter_temporal("2020-09-01", "2020-09-10")
 
 
-Note that :meth:`~openeo.rest.connection.Connection.datacube_from_process` can be
+Note that :py:meth:`~openeo.rest.connection.Connection.datacube_from_process` can be
 used with all kind of processes, not only user-defined processes.
 For example, while this is not exactly a real EO data use case,
 it will produce a valid openEO process graph that can be executed::
@@ -60,8 +60,8 @@ it will produce a valid openEO process graph that can be executed::
 
 .. _datacube_from_json:
 
-Construct DataCube from JSON
-==============================
+Construct a DataCube from JSON
+===============================
 
 openEO process graphs are typically stored and published in JSON format.
 Most notably, user-defined processes are transferred between openEO client
@@ -81,8 +81,8 @@ and back-end in a JSON structure roughly like in this example::
         ...
 
 
-It is possible to construct a :class:`~openeo.rest.datacube.DataCube` object that corresponds with this
-process graph with the :meth:`Connection.datacube_from_json <openeo.rest.connection.Connection.datacube_from_json>` method.
+It is possible to construct a :py:class:`~openeo.rest.datacube.DataCube` object that corresponds with this
+process graph with the :py:meth:`Connection.datacube_from_json <openeo.rest.connection.Connection.datacube_from_json>` method.
 It can be given one of:
 
     - a raw JSON string,
@@ -99,16 +99,20 @@ The JSON structure should be one of:
 Some examples
 ---------------
 
-Load a :class:`~openeo.rest.datacube.DataCube` from a raw JSON string, containing a
-simple "flat graph" representation::
+Load a :py:class:`~openeo.rest.datacube.DataCube` from a raw JSON string, containing a
+simple "flat graph" representation:
+
+.. code-block:: python
 
     raw_json = '''{
         "lc": {"process_id": "load_collection", "arguments": {"id": "SENTINEL2_TOC"}},
         "ak": {"process_id": "apply_kernel", "arguments": {"data": {"from_node": "lc"}, "kernel": [[1,2,1],[2,5,2],[1,2,1]]}, "result": true}
     }'''
     cube = connection.datacube_from_json(raw_json)
 
-Load from a raw JSON string, containing a mapping with "process_graph" and "parameters"::
+Load from a raw JSON string, containing a mapping with "process_graph" and "parameters":
+
+.. code-block:: python
 
     raw_json = '''{
         "parameters": [
@@ -121,42 +125,58 @@ Load from a raw JSON string, containing a mapping with "process_graph" and "para
     }'''
     cube = connection.datacube_from_json(raw_json)
 
-Load directly from a file or URL containing these kind of JSON representations::
+Load directly from a local file or URL containing these kind of JSON representations:
 
+.. code-block:: python
+
+    # Local file
     cube = connection.datacube_from_json("path/to/my_udp.json")
 
-    cube = connection.datacube_from_json("https://openeo.example/process_graphs/my_udp")
+    # URL
+    cube = connection.datacube_from_json("https://example.com/my_udp.json")
 
 
 Parameterization
 -----------------
 
 When the process graph uses parameters, you must specify the desired parameter values
-at the time of calling :meth:`Connection.datacube_from_json <openeo.rest.connection.Connection.datacube_from_json>`.
+at the time of calling :py:meth:`Connection.datacube_from_json <openeo.rest.connection.Connection.datacube_from_json>`.
+
+For example, take this simple toy example of a process graph that takes the sum of 5 and a parameter "increment":
 
-For example, take this simple toy example of a process graph that takes the sum of 5 and a parameter "increment"::
+.. code-block:: python
 
     raw_json = '''{"add": {
         "process_id": "add",
         "arguments": {"x": 5, "y": {"from_parameter": "increment"}},
         "result": true
     }}'''
 
-Trying to build a :class:`~openeo.rest.datacube.DataCube` from it without specifying parameter values will fail
-like this::
+Trying to build a :py:class:`~openeo.rest.datacube.DataCube` from it without specifying parameter values will fail
+like this:
+
+.. code-block:: pycon
 
     >>> cube = connection.datacube_from_json(raw_json)
     ProcessGraphVisitException: No substitution value for parameter 'increment'.
 
-Instead, specify the parameter value::
+Instead, specify the parameter value:
+
+.. code-block:: pycon
+    :emphasize-lines: 3
 
-    >>> cube = connection.datacube_from_json(raw_json, parameters={"increment": 4})
+    >>> cube = connection.datacube_from_json(
+    ...    raw_json,
+    ...    parameters={"increment": 4},
+    ... )
     >>> cube.execute()
     9
 
 
 Parameters can also be defined with default values, which will be used when they are not specified
-in the :meth:`Connection.datacube_from_json <openeo.rest.connection.Connection.datacube_from_json>` call::
+in the :py:meth:`Connection.datacube_from_json <openeo.rest.connection.Connection.datacube_from_json>` call:
+
+.. code-block:: python
 
     raw_json = '''{
         "parameters": [

openeo/rest/connection.py

@@ -1139,9 +1139,13 @@ def datacube_from_flat_graph(self, flat_graph: dict, parameters: Optional[dict]
         """
         Construct a :py:class:`DataCube` from a flat dictionary representation of a process graph.
 
+        .. seealso:: :ref:`datacube_from_json`, :py:meth:`~openeo.rest.connection.Connection.datacube_from_json`
+
         :param flat_graph: flat dictionary representation of a process graph
             or a process dictionary with such a flat process graph under a "process_graph" field
             (and optionally parameter metadata under a "parameters" field).
+        :param parameters: Optional dictionary mapping parameter names to parameter values
+            to use for parameters occurring in the process graph (e.g. as used in user-defined processes)
         :return: A :py:class:`DataCube` corresponding with the operations encoded in the process graph
         """
         parameters = parameters or {}
@@ -1162,7 +1166,11 @@ def datacube_from_json(self, src: Union[str, Path], parameters: Optional[dict] =
         """
         Construct a :py:class:`DataCube` from JSON resource containing (flat) process graph representation.
 
+        .. seealso:: :ref:`datacube_from_json`, :py:meth:`~openeo.rest.connection.Connection.datacube_from_flat_graph`
+
         :param src: raw JSON string, URL to JSON resource or path to local JSON file
+        :param parameters: Optional dictionary mapping parameter names to parameter values
+            to use for parameters occurring in the process graph (e.g. as used in user-defined processes)
         :return: A :py:class:`DataCube` corresponding with the operations encoded in the process graph
         """
         return self.datacube_from_flat_graph(load_json_resource(src), parameters=parameters)