├── requirements.txt ├── earthengine-api.inv ├── inventory ├── earthengine-api.inv ├── ee_class_list.json └── generate.py ├── pyproject.toml ├── .pre-commit-config.yaml ├── noxfile.py ├── LICENSE ├── README.md └── .gitignore /requirements.txt: -------------------------------------------------------------------------------- 1 | earthengine-api 2 | sphobjinv -------------------------------------------------------------------------------- /earthengine-api.inv: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gee-community/sphinx-inventory/main/earthengine-api.inv -------------------------------------------------------------------------------- /inventory/earthengine-api.inv: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/gee-community/sphinx-inventory/main/inventory/earthengine-api.inv -------------------------------------------------------------------------------- /inventory/ee_class_list.json: -------------------------------------------------------------------------------- 1 | [ 2 | "Array", 3 | "Blob", 4 | "Classifier", 5 | "Clusterer", 6 | "ConfusionMatrix", 7 | "Date", 8 | "DateRange", 9 | "Dictionary", 10 | "ErrorMargin", 11 | "Feature", 12 | "FeatureCollection", 13 | "Filter", 14 | "Geometry", 15 | "Image", 16 | "ImageCollection", 17 | "Join", 18 | "Kernel", 19 | "List", 20 | "Model", 21 | "Number", 22 | "PixelType", 23 | "Projection", 24 | "Reducer", 25 | "String", 26 | "Terrain", 27 | "Algorithms" 28 | ] 29 | -------------------------------------------------------------------------------- /pyproject.toml: -------------------------------------------------------------------------------- 1 | [tool.ruff] 2 | line-length = 100 3 | ignore-init-module-imports = true 4 | fix = true 5 | select = ["E", "F", "W", "I", "D", "RUF"] 6 | ignore = [ 7 | "D212", # Multi-line docstring | We use D213 8 | "E731", # Do not assign a `lambda` expression, use a `def` | I prefer to use lambda 9 | ] 10 | 11 | [tool.ruff.flake8-quotes] 12 | docstring-quotes = "double" 13 | 14 | [tool.ruff.pydocstyle] 15 | convention = "google" 16 | 17 | [tool.mypy] 18 | scripts_are_modules = true 19 | ignore_missing_imports = true 20 | install_types = true 21 | non_interactive = true 22 | warn_redundant_casts = true -------------------------------------------------------------------------------- /.pre-commit-config.yaml: -------------------------------------------------------------------------------- 1 | default_install_hook_types: [pre-commit, commit-msg] 2 | 3 | repos: 4 | - repo: "https://github.com/commitizen-tools/commitizen" 5 | rev: "v2.18.0" 6 | hooks: 7 | - id: commitizen 8 | stages: [commit-msg] 9 | 10 | - repo: "https://github.com/pre-commit/mirrors-prettier" 11 | rev: "v2.7.1" 12 | hooks: 13 | - id: prettier 14 | stages: [pre-commit] 15 | exclude: tests\/test_.+\. 16 | 17 | - repo: https://github.com/charliermarsh/ruff-pre-commit 18 | rev: "v0.7.0" 19 | hooks: 20 | - id: ruff 21 | stages: [pre-commit] 22 | - id: ruff-format 23 | stages: [pre-commit] 24 | 25 | - repo: https://github.com/codespell-project/codespell 26 | rev: v2.2.4 27 | hooks: 28 | - id: codespell 29 | stages: [pre-commit] 30 | additional_dependencies: 31 | - tomli 32 | -------------------------------------------------------------------------------- /noxfile.py: -------------------------------------------------------------------------------- 1 | """All the process that can be run using nox. 2 | 3 | The nox run are build in isolated environment that will be stored in .nox. to force the venv 4 | update, remove the .nox/xxx folder. 5 | """ 6 | 7 | import nox 8 | 9 | nox.options.sessions = ["lint", "mypy"] 10 | 11 | 12 | @nox.session(reuse_venv=True) 13 | def lint(session): 14 | """Apply the pre-commits.""" 15 | session.install("pre-commit") 16 | session.run("pre-commit", "run", "--all-files", *session.posargs) 17 | 18 | 19 | @nox.session(reuse_venv=True) 20 | def mypy(session): 21 | """Run a mypy check of the lib.""" 22 | session.install("mypy") 23 | test_files = session.posargs or ["inventory"] 24 | session.run("mypy", *test_files) 25 | 26 | 27 | @nox.session(reuse_venv=True) 28 | def generate(session): 29 | """Generate the inventory file.""" 30 | session.install("-r", "./requirements.txt") 31 | session.run("python", "inventory/generate.py", silent=False) 32 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2024 Rambaud Pierrick 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # sphinx-inventory 2 | 3 | The code used to generate the sphinx inventory of the all the Google Earth Engine objects. 4 | 5 | ## Usage 6 | 7 | This repository is generating and storing the Sphinx inventory of the GEE objects. 8 | The inventory is generated by the `generate_inventory.py` script. 9 | The script is using the `ee` module to get the list of the objects and their methods. 10 | The inventory is stored in the `inventory/earthengine-api.inv` file. 11 | The `inventory.json` file is used by the `sphinx` to generate the documentation. 12 | 13 | To link Earth Engine object in your sphinx documentation, add the following to your `conf.py` file: 14 | 15 | ```python 16 | intersphinx_mapping = { 17 | 'ee': ( 18 | "https://developers.google.com/earth-engine/apidocs", 19 | "https://raw.githubusercontent.com/gee-community/sphinx-inventory/refs/heads/main/inventory/earthengine-api.inv" 20 | ), 21 | } 22 | ``` 23 | 24 | Then you can use the `:py:class:'ee.Image'` role to link the Earth Engine object in your Sphinx files. 25 | It will appear as [`ee.Image`](https://developers.google.com/earth-engine/apidocs/ee-image) in the built documentation. 26 | 27 | 28 | > [!NOTE] 29 | > - To know more about `earthengine-api` read their documentation [here](https://developers.google.com/earth-engine) 30 | > - To know more about `sphinx` read their documentation [here](https://www.sphinx-doc.org/en/master/) 31 | > - To know more about `sphinx.ext.intersphinx` usage read their documentation [here](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html) 32 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Byte-compiled / optimized / DLL files 2 | __pycache__/ 3 | *.py[cod] 4 | *$py.class 5 | 6 | # C extensions 7 | *.so 8 | 9 | # Distribution / packaging 10 | .Python 11 | build/ 12 | develop-eggs/ 13 | dist/ 14 | downloads/ 15 | eggs/ 16 | .eggs/ 17 | lib/ 18 | lib64/ 19 | parts/ 20 | sdist/ 21 | var/ 22 | wheels/ 23 | share/python-wheels/ 24 | *.egg-info/ 25 | .installed.cfg 26 | *.egg 27 | MANIFEST 28 | 29 | # PyInstaller 30 | # Usually these files are written by a python script from a template 31 | # before PyInstaller builds the exe, so as to inject date/other infos into it. 32 | *.manifest 33 | *.spec 34 | 35 | # Installer logs 36 | pip-log.txt 37 | pip-delete-this-directory.txt 38 | 39 | # Unit test / coverage reports 40 | htmlcov/ 41 | .tox/ 42 | .nox/ 43 | .coverage 44 | .coverage.* 45 | .cache 46 | nosetests.xml 47 | coverage.xml 48 | *.cover 49 | *.py,cover 50 | .hypothesis/ 51 | .pytest_cache/ 52 | cover/ 53 | 54 | # Translations 55 | *.mo 56 | *.pot 57 | 58 | # Django stuff: 59 | *.log 60 | local_settings.py 61 | db.sqlite3 62 | db.sqlite3-journal 63 | 64 | # Flask stuff: 65 | instance/ 66 | .webassets-cache 67 | 68 | # Scrapy stuff: 69 | .scrapy 70 | 71 | # Sphinx documentation 72 | docs/_build/ 73 | 74 | # PyBuilder 75 | .pybuilder/ 76 | target/ 77 | 78 | # Jupyter Notebook 79 | .ipynb_checkpoints 80 | 81 | # IPython 82 | profile_default/ 83 | ipython_config.py 84 | 85 | # pyenv 86 | # For a library or package, you might want to ignore these files since the code is 87 | # intended to run in multiple environments; otherwise, check them in: 88 | # .python-version 89 | 90 | # pipenv 91 | # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. 92 | # However, in case of collaboration, if having platform-specific dependencies or dependencies 93 | # having no cross-platform support, pipenv may install dependencies that don't work, or not 94 | # install all needed dependencies. 95 | #Pipfile.lock 96 | 97 | # poetry 98 | # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. 99 | # This is especially recommended for binary packages to ensure reproducibility, and is more 100 | # commonly ignored for libraries. 101 | # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control 102 | #poetry.lock 103 | 104 | # pdm 105 | # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. 106 | #pdm.lock 107 | # pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it 108 | # in version control. 109 | # https://pdm.fming.dev/latest/usage/project/#working-with-version-control 110 | .pdm.toml 111 | .pdm-python 112 | .pdm-build/ 113 | 114 | # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm 115 | __pypackages__/ 116 | 117 | # Celery stuff 118 | celerybeat-schedule 119 | celerybeat.pid 120 | 121 | # SageMath parsed files 122 | *.sage.py 123 | 124 | # Environments 125 | .env 126 | .venv 127 | env/ 128 | venv/ 129 | ENV/ 130 | env.bak/ 131 | venv.bak/ 132 | 133 | # Spyder project settings 134 | .spyderproject 135 | .spyproject 136 | 137 | # Rope project settings 138 | .ropeproject 139 | 140 | # mkdocs documentation 141 | /site 142 | 143 | # mypy 144 | .mypy_cache/ 145 | .dmypy.json 146 | dmypy.json 147 | 148 | # Pyre type checker 149 | .pyre/ 150 | 151 | # pytype static type analyzer 152 | .pytype/ 153 | 154 | # Cython debug symbols 155 | cython_debug/ 156 | 157 | # PyCharm 158 | # JetBrains specific template is maintained in a separate JetBrains.gitignore that can 159 | # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore 160 | # and can be added to the global gitignore or merged into this file. For a more nuclear 161 | # option (not recommended) you can uncomment the following to ignore the entire idea folder. 162 | #.idea/ 163 | -------------------------------------------------------------------------------- /inventory/generate.py: -------------------------------------------------------------------------------- 1 | """The code used to generate the sphinx inventory of the GEE objects.""" 2 | 3 | import inspect 4 | import json 5 | import logging 6 | from pathlib import Path 7 | 8 | import ee 9 | import sphobjinv as soi 10 | 11 | HERE = Path(__file__).parent 12 | """The current folder""" 13 | 14 | logger = logging.getLogger(__name__) 15 | """The logger for this module""" 16 | 17 | # create the inventory object 18 | logger.info("Generating the inventory file") 19 | inv = soi.Inventory() 20 | 21 | # add package information from the ee lib 22 | logger.info("Adding the package information") 23 | inv.project = "earthengine-api" 24 | inv.version = ee.__version__ 25 | 26 | # add the main module manually 27 | logger.info("Adding the main module") 28 | inv.objects.append( 29 | soi.DataObjStr( 30 | name=ee.__name__, 31 | domain="py", 32 | role=str(type(ee)), 33 | priority="1", 34 | uri="", 35 | dispname="-", 36 | ) 37 | ) 38 | 39 | # Not all the objects from ee should be added to the inventory as most of them are undocumented 40 | # the list have been carefully built manually and saved in a json file. For each object, all the 41 | # methods are added to the inventory. Some of them might not be documented but they will be removed 42 | # thanks to user feedback. 43 | logger.info("Adding the main classes and methods") 44 | class_list = json.loads((HERE / "ee_class_list.json").read_text()) 45 | public_members = lambda obj: [o for n, o in inspect.getmembers(obj) if not n.startswith("_")] 46 | for class_name in class_list: 47 | # first inject the class itself 48 | cls = getattr(ee, class_name) 49 | atoms = ["ee", class_name] 50 | inv.objects.append( 51 | soi.DataObjStr( 52 | name=".".join(atoms), 53 | domain="py", 54 | role="class", 55 | priority="1", 56 | uri="-".join(atoms).lower(), 57 | dispname="-", 58 | ) 59 | ) 60 | 61 | # then all its downstream methods 62 | method_list = public_members(cls) 63 | for meth in method_list: 64 | atoms = ["ee", class_name, meth.__name__] 65 | inv.objects.append( 66 | soi.DataObjStr( 67 | name=".".join(atoms), 68 | domain="py", 69 | role="method", 70 | priority="1", 71 | uri="-".join(atoms).lower(), 72 | dispname="-", 73 | ) 74 | ) 75 | 76 | # Initialize and Authenticate even if they start with a capital letter are not objects but 77 | # functions that must be documented 78 | logger.info("Adding the 2 oauth functions") 79 | for func in ["Initialize", "Authenticate"]: 80 | atoms = ["ee", func] 81 | inv.objects.append( 82 | soi.DataObjStr( 83 | name=".".join(atoms), 84 | domain="py", 85 | role="function", 86 | priority="1", 87 | uri="-".join(atoms).lower(), 88 | dispname="-", 89 | ) 90 | ) 91 | 92 | # From the ee.data module, only the methods should be added into the inventory as the rest is 93 | # undocumented so it reduces vastly the number of items to update 94 | logger.info("Adding the data module") 95 | meth_list = [ 96 | o 97 | for n, o in inspect.getmembers(ee.data) 98 | if not (n.startswith("_") or inspect.isclass(o) or n[0].isupper()) 99 | ] 100 | for meth in meth_list: 101 | atoms = ["ee", "data", meth.__name__] 102 | inv.objects.append( 103 | soi.DataObjStr( 104 | name=".".join(atoms), 105 | domain="py", 106 | role="method", 107 | priority="1", 108 | uri="-".join(atoms).lower(), 109 | dispname="-", 110 | ) 111 | ) 112 | 113 | # batch module is only embedding 5 abstract classes that manage exportation processes. 114 | # The rest should remain undocumented 115 | logger.info("Adding the batch module") 116 | batch_classes = public_members(ee.batch.Export) 117 | for cls in batch_classes: 118 | method_list = public_members(cls) 119 | for meth in method_list: 120 | atoms = ["ee", "batch", "Export", cls.__name__, meth.__name__] 121 | inv.objects.append( 122 | soi.DataObjStr( 123 | name=".".join(atoms), 124 | domain="py", 125 | role="method", 126 | priority="1", 127 | uri="-".join(atoms[2:]).lower(), 128 | dispname="-", 129 | ) 130 | ) 131 | 132 | # export the file as a inventory file in the repository 133 | logger.info("Writing the inventory file") 134 | text = inv.data_file(contract=True) 135 | ztext = soi.compress(text) 136 | soi.writebytes(str(HERE / "earthengine-api.inv"), ztext) 137 | 138 | logger.info(f"Inventory file generated with {len(inv.objects)} objects.") 139 | --------------------------------------------------------------------------------