docs: update documentation content

.pre-commit-config.yaml

@@ -32,16 +32,16 @@ repos:
   #      - id: doc8
   #        stages: [pre-commit]
 
-  - repo: https://github.com/FHPythonUtils/LicenseCheck
-    rev: "2023.1.1"
-    hooks:
-      - id: licensecheck
-        stages: [pre-commit]
-
   - repo: https://github.com/codespell-project/codespell
     rev: v2.2.4
     hooks:
       - id: codespell
         stages: [pre-commit]
         additional_dependencies:
           - tomli
+
+  - repo: "https://github.com/kynan/nbstripout"
+    rev: "0.5.0"
+    hooks:
+      - id: nbstripout
+        stages: [pre-commit]

docs/_extension/api_admonition.py

@@ -0,0 +1,74 @@
+"""A directive to generate an API admonition."""
+
+from typing import Any, Dict
+
+from docutils import nodes
+from docutils.parsers.rst import directives
+from docutils.parsers.rst.directives.admonitions import BaseAdmonition
+from sphinx.application import Sphinx
+from sphinx.util import logging
+from sphinx.util.docutils import SphinxDirective
+from sphinx.writers.html5 import HTML5Translator
+
+logger = logging.getLogger(__name__)
+
+
+class api_node(nodes.Admonition, nodes.Element):
+    pass
+
+
+def visit_api_node(self: HTML5Translator, node: api_node) -> None:
+    self.visit_admonition(node)
+
+
+def depart_api_node(self: HTML5Translator, node: api_node) -> None:
+    self.depart_admonition(node)
+
+
+class APIAdmonitionDirective(BaseAdmonition, SphinxDirective):
+    """An API entry, displayed (if configured) in the form of an admonition."""
+
+    node_class = api_node
+    has_content = True
+    required_arguments = 0
+    optional_arguments = 0
+    final_argument_whitespace = False
+    option_spec = {
+        "class": directives.class_option,
+        "name": directives.unchanged,
+    }
+
+    def run(self) -> list[nodes.Node]:
+        if not self.options.get("class"):
+            self.options["class"] = ["admonition-api"]
+
+        (api,) = super().run()
+        if isinstance(api, nodes.system_message):
+            return [api]
+        elif isinstance(api, api_node):
+            api.insert(0, nodes.title(text="See API"))
+            api["docname"] = self.env.docname
+            self.add_name(api)
+            self.set_source_info(api)
+            self.state.document.note_explicit_target(api)
+            return [api]
+        else:
+            raise RuntimeError  # never reached here
+
+
+def setup(app: Sphinx) -> Dict[str, Any]:
+    """Add custom configuration to sphinx app.
+
+    Args:
+        app: the Sphinx application
+
+    Returns:
+        the 2 parallel parameters set to ``True``.
+    """
+    app.add_directive("api", APIAdmonitionDirective)
+    app.add_node(api_node, html=(visit_api_node, depart_api_node))
+
+    return {
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

docs/_static/custom.css

@@ -4,3 +4,7 @@ div.highlight-console pre span.go::before {
   margin-right: 10px;
   margin-left: 5px;
 }
+
+div.admonition.admonition-api > .admonition-title::after {
+  content: "\f121"; /* the fa-code icon */
+}

docs/conf.py

@@ -7,12 +7,11 @@
 
 # -- Path setup ----------------------------------------------------------------
 import os
-import re
 import sys
 from datetime import datetime
 from pathlib import Path
 
-import ee
+import pytest_gee
 
 # add . to sys to import local extensions
 sys.path.append(str(Path(".").resolve()))
@@ -29,12 +28,14 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.intersphinx",
     "sphinx.ext.autosectionlabel",
+    "sphinxcontrib.icon",
     "sphinx_design",
     "sphinx_copybutton",
     "autoapi.extension",
     "jupyter_sphinx",
-    "nbsphinx",
+    "myst_nb",
     "_extension.docstring",
+    "_extension.api_admonition",
 ]
 exclude_patterns = ["**.ipynb_checkpoints"]
 
@@ -123,41 +124,18 @@
 # -- options for the autolabel extension ---------------------------------------
 autosectionlabel_prefix_document = True
 
-# -- options for nbsphinx ------------------------------------------------------
-nbsphinx_execute = "never"
+# -- options for myst-nb ------------------------------------------------------
+nb_execution_mode = "force"
 
 # -- Script to authenticate to Earthengine using a token -----------------------
 def gee_configure() -> None:
-    """Initialize earth engine according to the environment.
-
-    It will use the creddential file if the EARTHENGINE_TOKEN env variable exist.
-    Otherwise it use the simple Initialize command (asking the user to register if necessary).
-    """
-    # only do the initialization if the credential are missing
-    if False:
-        # if not ee.data._credentials:
-
-        # if the credentials token is asved in the environment use it
-        if "EARTHENGINE_TOKEN" in os.environ:
-
-            # get the token from environment variable
-            ee_token = os.environ["EARTHENGINE_TOKEN"]
-
-            # as long as RDT quote the token, we need to remove the quotes before writing
-            # the string to the file
-            pattern = r"^'[^']*'$"
-            if re.match(pattern, ee_token) is not None:
-                ee_token = ee_token[1:-1]
-
-            # write the token to the appropriate folder
-            credential_folder_path = Path.home() / ".config" / "earthengine"
-            credential_folder_path.mkdir(parents=True, exist_ok=True)
-            credential_file_path = credential_folder_path / "credentials"
-            credential_file_path.write_text(ee_token)
-
-        # if the user is in local development the authentication should
-        # already be available
-        ee.Initialize()
+    """Initialize earth engine according to the environment."""
+    if "EARTHENGINE_SERVICE_ACCOUNT" in os.environ:
+        pytest_gee.init_ee_from_service_account()
+    elif "EARTHENGINE_PROJECT" in os.environ:
+        pytest_gee.init_ee_from_token()
+    else:
+        raise ValueError("Cannot authenticate with Earth Engine.")
 
 
 gee_configure()