diff --git a/README.md b/README.md index f50b3ea..c1d13a4 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,33 @@ # gee-sphinx-inventory -The code used to generate the sphinx inventory of the GEE objects +The code used to generate the sphinx inventory of the GEE objects. + +## Usage + +This repository is generating and storing the Sphinx inventory of the GEE objects. +The inventory is generated by the `generate_inventory.py` script. +The script is using the `ee` module to get the list of the objects and their methods. +The inventory is stored in the `inventory/earthengine-api.inv` file. +The `inventory.json` file is used by the `sphinx` to generate the documentation. + +To link Earth Engine object in your sphinx documentation, add the following to your `conf.py` file: + +```python +intersphinx_mapping = { + 'ee': ( + "https://developers.google.com/earth-engine/apidocs", + "https://raw.githubusercontent.com/gee-community/sphinx-inventory/refs/heads/main/inventory/earthengine-api.inv" + ), +} +``` + +Then you can use the `:py:class:'ee.Image'` role to link the Earth Engine object in your Sphinx files. +It will appear as [`ee.Image`](https://developers.google.com/earth-engine/apidocs/ee-image) in the built documentation. + +```rst + +> [!NOTE] +> - To know more about `earthengine-api` read their documentation [here](https://developers.google.com/earth-engine) +> - To know more about `sphinx` read their documentation [here](https://www.sphinx-doc.org/en/master/) +> - To know more about `sphinx.ext.intersphinx` usage read their documentation [here](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html) +``` diff --git a/test.ipynb b/test.ipynb deleted file mode 100644 index 26f521a..0000000 --- a/test.ipynb +++ /dev/null @@ -1,536 +0,0 @@ -{ - "cells": [ - { - "cell_type": "code", - "execution_count": 1, - "metadata": {}, - "outputs": [], - "source": [ - "import ee\n", - "import sphobjinv as soi" - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "Inventory(project=None, version=None, source_type=)" - ] - }, - "execution_count": 2, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "inv = soi.Inventory()\n", - "inv" - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "Inventory(project='earthengine-api', version='1.2.0', source_type=)" - ] - }, - "execution_count": 3, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "inv.project = \"earthengine-api\"\n", - "inv.version = ee.__version__\n", - "inv" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "Inventory(project='earthengine-api', version='1.2.0', source_type=)" - ] - }, - "execution_count": 4, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "inv.objects.append(\n", - " soi.DataObjStr(\n", - " name=ee.__name__,\n", - " domain=\"py\",\n", - " role=str(type(ee)),\n", - " priority=\"1\",\n", - " uri=\"\",\n", - " dispname=\"-\",\n", - " )\n", - ")\n", - "inv" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "metadata": {}, - "outputs": [], - "source": [ - "import json\n", - "from pathlib import Path\n", - "\n", - "colab = \"#colab-python\"\n", - "\n", - "# for every class in the list add itself to the inventory and all the submethods\n", - "class_list = json.loads(Path(\"inventory/ee_class_list.json\").read_text())\n", - "for class_name in class_list:\n", - " c = getattr(ee, class_name)\n", - " inv.objects.append(\n", - " soi.DataObjStr(\n", - " name=\"ee.\" + class_name,\n", - " domain=\"py\",\n", - " role=\"class\",\n", - " priority=\"1\",\n", - " uri=\"ee-\" + class_name.lower(),\n", - " dispname=\"-\",\n", - " )\n", - " )\n", - "\n", - " # find all the methods in the object\n", - " methods = [m for m in dir(c) if not m.startswith(\"_\")]\n", - " for method_name in methods:\n", - " m = getattr(c, method_name)\n", - " inv.objects.append(\n", - " soi.DataObjStr(\n", - " name=\"ee.\" + class_name + \".\" + method_name,\n", - " domain=\"py\",\n", - " role=\"method\",\n", - " priority=\"1\",\n", - " uri=\"ee-\" + class_name.lower() + \"-\" + method_name.lower().replace(\"_\", \"-\"),\n", - " dispname=\"-\",\n", - " )\n", - " )" - ] - }, - { - "cell_type": "code", - "execution_count": 9, - "metadata": {}, - "outputs": [], - "source": [ - "for f in [\"Initialize\", \"Authenticate\"]:\n", - " inv.objects.append(\n", - " soi.DataObjStr(\n", - " name=\"ee.\" + f,\n", - " domain=\"py\",\n", - " role=\"function\",\n", - " priority=\"1\",\n", - " uri=\"ee-\" + f.lower().replace(\"_\", \"-\"),\n", - " dispname=\"-\",\n", - " )\n", - " )" - ] - }, - { - "cell_type": "code", - "execution_count": 17, - "metadata": {}, - "outputs": [], - "source": [ - "import inspect\n", - "\n", - "methods = [\n", - " m\n", - " for m, o in inspect.getmembers(ee.data)\n", - " if not (m.startswith(\"_\") or inspect.isclass(o) or m[0].isupper())\n", - "]\n", - "for method_name in methods:\n", - " inv.objects.append(\n", - " soi.DataObjStr(\n", - " name=\"ee.data.\" + method_name,\n", - " domain=\"py\",\n", - " role=\"function\",\n", - " priority=\"1\",\n", - " uri=\"ee-data-\" + method_name.lower().replace(\"_\", \"-\"),\n", - " dispname=\"-\",\n", - " )\n", - " )" - ] - }, - { - "cell_type": "code", - "execution_count": 26, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "[]" - ] - }, - "execution_count": 26, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "abstract_classes = [\n", - " cls for name, cls in inspect.getmembers(ee.batch.Export) if not name.startswith(\"_\")\n", - "]\n", - "for abstract_class in abstract_classes:\n", - " methods = [\n", - " meth for name, meth in inspect.getmembers(abstract_class) if not name.startswith(\"_\")\n", - " ]\n", - " for method in methods:\n", - " inv.objects.append(\n", - " soi.DataObjStr(\n", - " name=\"ee.batch.Export.\" + abstract_class.__name__ + \".\" + method.__name__,\n", - " domain=\"py\",\n", - " role=\"method\",\n", - " priority=\"1\",\n", - " uri=\"ee-batch-export-\"\n", - " + abstract_class.__name__\n", - " + \"-\"\n", - " + method.__name__.lower().replace(\"_\", \"-\"),\n", - " dispname=\"-\",\n", - " )\n", - " )" - ] - }, - { - "cell_type": "code", - "execution_count": 20, - "metadata": {}, - "outputs": [ - { - "data": { - "text/plain": [ - "[('Any', typing.Any),\n", - " ('Dict', typing.Dict),\n", - " ('Export', ee.batch.Export),\n", - " ('FORMAT_PREFIX_MAP', {'GEOTIFF': 'tiff', 'TFRECORD': 'tfrecord'}),\n", - " ('IMAGE_FORMAT_FIELD', 'fileFormat'),\n", - " ('IMAGE_FORMAT_OPTIONS_FIELD', 'formatOptions'),\n", - " ('List', typing.List),\n", - " ('NON_FILE_DESTINATIONS',\n", - " frozenset({,\n", - " ,\n", - " })),\n", - " ('Optional', typing.Optional),\n", - " ('Sequence', typing.Sequence),\n", - " ('Task', ee.batch.Task),\n", - " ('Union', typing.Union),\n", - " ('__builtins__',\n", - " {'__name__': 'builtins',\n", - " '__doc__': \"Built-in functions, types, exceptions, and other objects.\\n\\nThis module provides direct access to all 'built-in'\\nidentifiers of Python; for example, builtins.len is\\nthe full name for the built-in function len().\\n\\nThis module is not normally accessed explicitly by most\\napplications, but can be useful in modules that provide\\nobjects with the same name as a built-in value, but in\\nwhich the built-in of that name is also needed.\",\n", - " '__package__': '',\n", - " '__loader__': _frozen_importlib.BuiltinImporter,\n", - " '__spec__': ModuleSpec(name='builtins', loader=, origin='built-in'),\n", - " '__build_class__': ,\n", - " '__import__': ,\n", - " 'abs': ,\n", - " 'all': ,\n", - " 'any': ,\n", - " 'ascii': ,\n", - " 'bin': ,\n", - " 'breakpoint': ,\n", - " 'callable': ,\n", - " 'chr': ,\n", - " 'compile': ,\n", - " 'delattr': ,\n", - " 'dir': ,\n", - " 'divmod': ,\n", - " 'eval': ,\n", - " 'exec': ,\n", - " 'format': ,\n", - " 'getattr': ,\n", - " 'globals': ,\n", - " 'hasattr': ,\n", - " 'hash': ,\n", - " 'hex': ,\n", - " 'id': ,\n", - " 'input': >,\n", - " 'isinstance': ,\n", - " 'issubclass': ,\n", - " 'iter': ,\n", - " 'aiter': ,\n", - " 'len': ,\n", - " 'locals': ,\n", - " 'max': ,\n", - " 'min': ,\n", - " 'next': ,\n", - " 'anext': ,\n", - " 'oct': ,\n", - " 'ord': ,\n", - " 'pow': ,\n", - " 'print': ,\n", - " 'repr': ,\n", - " 'round': ,\n", - " 'setattr': ,\n", - " 'sorted': ,\n", - " 'sum': ,\n", - " 'vars': ,\n", - " 'None': None,\n", - " 'Ellipsis': Ellipsis,\n", - " 'NotImplemented': NotImplemented,\n", - " 'False': False,\n", - " 'True': True,\n", - " 'bool': bool,\n", - " 'memoryview': memoryview,\n", - " 'bytearray': bytearray,\n", - " 'bytes': bytes,\n", - " 'classmethod': classmethod,\n", - " 'complex': complex,\n", - " 'dict': dict,\n", - " 'enumerate': enumerate,\n", - " 'filter': filter,\n", - " 'float': float,\n", - " 'frozenset': frozenset,\n", - " 'property': property,\n", - " 'int': int,\n", - " 'list': list,\n", - " 'map': map,\n", - " 'object': object,\n", - " 'range': range,\n", - " 'reversed': reversed,\n", - " 'set': set,\n", - " 'slice': slice,\n", - " 'staticmethod': staticmethod,\n", - " 'str': str,\n", - " 'super': super,\n", - " 'tuple': tuple,\n", - " 'type': type,\n", - " 'zip': zip,\n", - " '__debug__': True,\n", - " 'BaseException': BaseException,\n", - " 'BaseExceptionGroup': BaseExceptionGroup,\n", - " 'Exception': Exception,\n", - " 'GeneratorExit': GeneratorExit,\n", - " 'KeyboardInterrupt': KeyboardInterrupt,\n", - " 'SystemExit': SystemExit,\n", - " 'ArithmeticError': ArithmeticError,\n", - " 'AssertionError': AssertionError,\n", - " 'AttributeError': AttributeError,\n", - " 'BufferError': BufferError,\n", - " 'EOFError': EOFError,\n", - " 'ImportError': ImportError,\n", - " 'LookupError': LookupError,\n", - " 'MemoryError': MemoryError,\n", - " 'NameError': NameError,\n", - " 'OSError': OSError,\n", - " 'ReferenceError': ReferenceError,\n", - " 'RuntimeError': RuntimeError,\n", - " 'StopAsyncIteration': StopAsyncIteration,\n", - " 'StopIteration': StopIteration,\n", - " 'SyntaxError': SyntaxError,\n", - " 'SystemError': SystemError,\n", - " 'TypeError': TypeError,\n", - " 'ValueError': ValueError,\n", - " 'Warning': Warning,\n", - " 'FloatingPointError': FloatingPointError,\n", - " 'OverflowError': OverflowError,\n", - " 'ZeroDivisionError': ZeroDivisionError,\n", - " 'BytesWarning': BytesWarning,\n", - " 'DeprecationWarning': DeprecationWarning,\n", - " 'EncodingWarning': EncodingWarning,\n", - " 'FutureWarning': FutureWarning,\n", - " 'ImportWarning': ImportWarning,\n", - " 'PendingDeprecationWarning': PendingDeprecationWarning,\n", - " 'ResourceWarning': ResourceWarning,\n", - " 'RuntimeWarning': RuntimeWarning,\n", - " 'SyntaxWarning': SyntaxWarning,\n", - " 'UnicodeWarning': UnicodeWarning,\n", - " 'UserWarning': UserWarning,\n", - " 'BlockingIOError': BlockingIOError,\n", - " 'ChildProcessError': ChildProcessError,\n", - " 'ConnectionError': ConnectionError,\n", - " 'FileExistsError': FileExistsError,\n", - " 'FileNotFoundError': FileNotFoundError,\n", - " 'InterruptedError': InterruptedError,\n", - " 'IsADirectoryError': IsADirectoryError,\n", - " 'NotADirectoryError': NotADirectoryError,\n", - " 'PermissionError': PermissionError,\n", - " 'ProcessLookupError': ProcessLookupError,\n", - " 'TimeoutError': TimeoutError,\n", - " 'IndentationError': IndentationError,\n", - " 'IndexError': IndexError,\n", - " 'KeyError': KeyError,\n", - " 'ModuleNotFoundError': ModuleNotFoundError,\n", - " 'NotImplementedError': NotImplementedError,\n", - " 'RecursionError': RecursionError,\n", - " 'UnboundLocalError': UnboundLocalError,\n", - " 'UnicodeError': UnicodeError,\n", - " 'BrokenPipeError': BrokenPipeError,\n", - " 'ConnectionAbortedError': ConnectionAbortedError,\n", - " 'ConnectionRefusedError': ConnectionRefusedError,\n", - " 'ConnectionResetError': ConnectionResetError,\n", - " 'TabError': TabError,\n", - " 'UnicodeDecodeError': UnicodeDecodeError,\n", - " 'UnicodeEncodeError': UnicodeEncodeError,\n", - " 'UnicodeTranslateError': UnicodeTranslateError,\n", - " 'ExceptionGroup': ExceptionGroup,\n", - " 'EnvironmentError': OSError,\n", - " 'IOError': OSError,\n", - " 'open': ,\n", - " 'copyright': Copyright (c) 2001-2023 Python Software Foundation.\n", - " All Rights Reserved.\n", - " \n", - " Copyright (c) 2000 BeOpen.com.\n", - " All Rights Reserved.\n", - " \n", - " Copyright (c) 1995-2001 Corporation for National Research Initiatives.\n", - " All Rights Reserved.\n", - " \n", - " Copyright (c) 1991-1995 Stichting Mathematisch Centrum, Amsterdam.\n", - " All Rights Reserved.,\n", - " 'credits': Thanks to CWI, CNRI, BeOpen.com, Zope Corporation and a cast of thousands\n", - " for supporting Python development. See www.python.org for more information.,\n", - " 'license': Type license() to see the full license text,\n", - " 'help': Type help() for interactive help, or help(object) for help about object.,\n", - " 'execfile': ,\n", - " 'runfile': ,\n", - " '__IPYTHON__': True,\n", - " 'display': ,\n", - " 'get_ipython': >}),\n", - " ('__cached__',\n", - " '/home/prambaud/miniconda3/envs/inventory/lib/python3.11/site-packages/ee/__pycache__/batch.cpython-311.pyc'),\n", - " ('__doc__',\n", - " 'An interface to the Earth Engine batch processing system.\\n\\nUse the static methods on the Export class to create export tasks, call start()\\non them to launch them, then poll status() to find out when they are finished.\\nThe public function styling uses camelCase to match the JavaScript names.\\n'),\n", - " ('__file__',\n", - " '/home/prambaud/miniconda3/envs/inventory/lib/python3.11/site-packages/ee/batch.py'),\n", - " ('__loader__',\n", - " <_frozen_importlib_external.SourceFileLoader at 0x7fc9b52a0690>),\n", - " ('__name__', 'ee.batch'),\n", - " ('__package__', 'ee'),\n", - " ('__spec__',\n", - " ModuleSpec(name='ee.batch', loader=<_frozen_importlib_external.SourceFileLoader object at 0x7fc9b52a0690>, origin='/home/prambaud/miniconda3/envs/inventory/lib/python3.11/site-packages/ee/batch.py')),\n", - " ('_build_bigquery_destination',\n", - " 'Dict[str, Any]'>),\n", - " ('_build_cloud_storage_destination',\n", - " 'Dict[str, Any]'>),\n", - " ('_build_drive_destination',\n", - " 'Dict[str, Any]'>),\n", - " ('_build_earth_engine_destination',\n", - " 'Dict[str, Any]'>),\n", - " ('_build_feature_view_destination',\n", - " 'Dict[str, Any]'>),\n", - " ('_build_image_file_export_options',\n", - " 'Dict[str, Any]'>),\n", - " ('_build_ranking_options',\n", - " 'Optional[Dict[str, Any]]'>),\n", - " ('_build_table_file_export_options',\n", - " 'Dict[str, Any]'>),\n", - " ('_build_thinning_options',\n", - " 'Optional[Dict[str, Any]]'>),\n", - " ('_build_tile_options',\n", - " 'Dict[str, Any]'>),\n", - " ('_build_video_file_export_options',\n", - " 'Dict[str, Any]'>),\n", - " ('_build_video_options',\n", - " 'Dict[str, Any]'>),\n", - " ('_canonicalize_parameters',\n", - " ),\n", - " ('_canonicalize_region',\n", - " 'geometry.Geometry'>),\n", - " ('_capture_parameters',\n", - " 'Dict[str, Any]'>),\n", - " ('_cloud_api_utils',\n", - " ),\n", - " ('_create_export_task',\n", - " 'Task'>),\n", - " ('_get_rank_by_one_thing_rule',\n", - " 'Dict[str, Any]'>),\n", - " ('_get_ranking_rule',\n", - " 'Optional[Dict[str, List[Dict[str, Any]]]]'>),\n", - " ('_prepare_classifier_export_config',\n", - " 'Dict[str, Any]'>),\n", - " ('_prepare_image_export_config',\n", - " 'Dict[str, Any]'>),\n", - " ('_prepare_map_export_config',\n", - " 'Dict[str, Any]'>),\n", - " ('_prepare_table_export_config',\n", - " 'Dict[str, Any]'>),\n", - " ('_prepare_video_export_config',\n", - " 'Dict[str, Any]'>),\n", - " ('_transform_operation_to_task',\n", - " 'Task'>),\n", - " ('annotations', _Feature((3, 7, 0, 'beta', 1), None, 16777216)),\n", - " ('build_ingestion_time_parameters',\n", - " 'Dict[str, Any]'>),\n", - " ('data',\n", - " ),\n", - " ('ee_exception',\n", - " ),\n", - " ('enum',\n", - " ),\n", - " ('geometry',\n", - " ),\n", - " ('json',\n", - " ),\n", - " ('re',\n", - " )]" - ] - }, - "execution_count": 20, - "metadata": {}, - "output_type": "execute_result" - } - ], - "source": [ - "inspect.getmembers(ee.batch)" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "metadata": {}, - "outputs": [], - "source": [ - "text = inv.data_file(contract=True)\n", - "ztext = soi.compress(text)\n", - "soi.writebytes(\"earthengine-api.inv\", ztext)" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [] - } - ], - "metadata": { - "kernelspec": { - "display_name": "inventory", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.11.10" - } - }, - "nbformat": 4, - "nbformat_minor": 2 -}