Cleanup Api docs (#1688)

* Product not dataset type smh * Add lineage tree to model docs. * Cleanup masking module autodoc. * Documenting the index API a bit better, fixing various autodoc/autosummary issues. * Fix various Sphinx errors. * more fixes and tweaks * Update whats_new.rst * Sphinx gets me every time. * Found some more old stuff to update. * Spelling. * Rename metadtaType.rst to metadata-type.rst for consistency. * Update docs/installation/extending-odc.rst Co-authored-by: Ariana-B <[email protected]> * Update docs/installation/extending-odc.rst Co-authored-by: Ariana-B <[email protected]> --------- Co-authored-by: Ariana-B <[email protected]>
opendatacube · Dec 18, 2024 · 76b7999 · 76b7999
1 parent 63b65ff
commit 76b7999
Show file tree

Hide file tree

Showing 16 changed files with 115 additions and 126 deletions.
diff --git a/datacube/index/abstract/_index.py b/datacube/index/abstract/_index.py
@@ -235,21 +235,24 @@ def clone(self,
         Steps are:
 
         1) Clone all metadata types compatible with this index driver.
-           * Products and Datasets with incompatible metadata types are excluded from subsequent steps.
-           * Existing metadata types are skipped, but products and datasets associated with them are only
+           - Products and Datasets with incompatible metadata types are excluded from subsequent steps.
+           - Existing metadata types are skipped, but products and datasets associated with them are only
              excluded if the existing metadata type does not match the one from the origin index.
+
         2) Clone all products with "safe" metadata types.
-           * Products are included or excluded by metadata type as discussed above.
-           * Existing products are skipped, but datasets associated with them are only
+           - Products are included or excluded by metadata type as discussed above.
+           - Existing products are skipped, but datasets associated with them are only
              excluded if the existing product definition does not match the one from the origin index.
-        3)  Clone all datasets with "safe" products
-            * Datasets are included or excluded by product and metadata type, as discussed above.
-            * Archived datasets and locations are not cloned.
+
+        3) Clone all datasets with "safe" products
+           - Datasets are included or excluded by product and metadata type, as discussed above.
+           - Archived datasets and locations are not cloned.
+
         4) Clone all lineage relations that can be cloned.
-            * All lineage relations are skipped if either index driver does not support lineage,
-              or if skip_lineage is True.
-            * If this index does not support external lineage then lineage relations that reference datasets
-              that do not exist in this index after step 3 above are skipped.
+           - All lineage relations are skipped if either index driver does not support lineage,
+             or if skip_lineage is True.
+           - If this index does not support external lineage then lineage relations that reference datasets
+             that do not exist in this index after step 3 above are skipped.
 
         API Note: This API method is not finalised and may be subject to change.
 

diff --git a/datacube/index/abstract/_types.py b/datacube/index/abstract/_types.py
@@ -16,14 +16,15 @@
 class BatchStatus(NamedTuple):
     """
     A named tuple representing the results of a batch add operation:
-    - completed: Number of objects added to theMay be None for internal functions and for datasets.
-    - skipped: Number of objects skipped, either because they already exist
-      or the documents are invalid for this driver.
-    - seconds_elapsed: seconds elapsed during the bulk add operation;
-    - safe: an optional list of names of bulk added objects that are safe to be
-      used for lower level bulk adds. Includes objects added, and objects skipped
-      because they already exist in the index and are identical to the version
-      being added.  May be None for internal functions and for datasets.
+
+      - completed: Number of objects added to theMay be None for internal functions and for datasets.
+      - skipped: Number of objects skipped, either because they already exist
+        or the documents are invalid for this driver.
+      - seconds_elapsed: seconds elapsed during the bulk add operation;
+      - safe: an optional list of names of bulk added objects that are safe to be
+        used for lower level bulk adds. Includes objects added, and objects skipped
+        because they already exist in the index and are identical to the version
+        being added.  May be None for internal functions and for datasets.
     """
     completed: int
     skipped: int

diff --git a/docs/about/index.rst b/docs/about/index.rst
@@ -9,4 +9,3 @@ About
    glossary
    license
    release_process
-   MIGRATION-1.8-to-1.9
diff --git a/docs/about/license.rst b/docs/about/license.rst
@@ -3,6 +3,4 @@
 ODC License
 ***********
 
-.. literalinclude::
-
-    ../../LICENSE
+.. literalinclude:: ../../LICENSE
diff --git a/docs/about/whats_new.rst b/docs/about/whats_new.rst
@@ -8,7 +8,8 @@ What's New
 v1.9.next
 =========
 
-- Further metadata fix for new lineage API (:pull:`1690`) 
+- API autodocs cleanup (:pull:`1688`)
+- Further metadata fix for new lineage API (:pull:`1690`)
 
 v1.9.0-rc13 (16th December 2024)
 ===============================

diff --git a/docs/api/core-classes/lineage-tree.rst b/docs/api/core-classes/lineage-tree.rst
@@ -0,0 +1,17 @@
+===========
+LineageTree
+===========
+
+The ``LineageTree`` class is used by the Lineage API for describing lineage trees of datasets.
+
+..note:
+   Only the ``postgis`` index driver supports the Lineage API.
+
+
+.. currentmodule:: datacube.model
+
+.. autoclass:: LineageDirection
+   :members:
+
+.. autoclass:: LineageTree
+   :members:
diff --git a/docs/api/core-classes/metadata-type.rst b/docs/api/core-classes/metadata-type.rst
@@ -0,0 +1,9 @@
+=============
+Metadata Type
+=============
+
+
+.. currentmodule:: datacube.model
+
+.. autoclass:: MetadataType
+   :members:
diff --git a/docs/api/core-classes/metadataType.rst b/docs/api/core-classes/metadataType.rst
diff --git a/docs/api/core-classes/product.rst b/docs/api/core-classes/product.rst
@@ -1,9 +1,8 @@
-============
-Dataset Type
-============
+=======
+Product
+=======
 
-.. currentmodule:: datacube
-
-.. autoclass:: datacube.model.Product
+.. currentmodule:: datacube.model
 
+.. autoclass:: Product
    :members:
diff --git a/docs/api/index.rst b/docs/api/index.rst
@@ -14,7 +14,8 @@ The following pages provide a full API reference for the ``datacube`` python lib
     core-classes/product
     core-classes/geometry
     core-classes/measurement
-    core-classes/metadataType
+    core-classes/metadata-type
+    core-classes/lineage-tree
     core-classes/range
     core-classes/query
 
@@ -35,6 +36,7 @@ The following pages provide a full API reference for the ``datacube`` python lib
 
     indexed-data/dataset-writing
     indexed-data/product-writing
+    indexed-data/index-api
 
 
 .. toctree::

diff --git a/docs/api/indexed-data/dataset-writing.rst b/docs/api/indexed-data/dataset-writing.rst
@@ -1,6 +1,7 @@
 ===============
 Dataset Writing
 ===============
+
 When connected to an ODC Database, these methods are available for adding, updating and archiving datasets:
 
 .. code-block:: bash
@@ -23,3 +24,10 @@ When connected to an ODC Database, these methods are available for adding, updat
    restore
    restore_location
    update
+
+The following "high level" API helps you get new datasets into a form ready to pass to the above methods
+in a particular index.
+
+.. currentmodule:: datacube.index.hl
+.. autoclass:: Doc2Dataset
+   :members:
diff --git a/docs/api/indexed-data/index-api.rst b/docs/api/indexed-data/index-api.rst
@@ -0,0 +1,11 @@
+=========
+Index API
+=========
+
+ODC index drivers implement the interfaces defined in:
+
+.. autosummary::
+   :toctree:
+   :recursive:
+
+   datacube.index.abstract
diff --git a/docs/api/indexed-data/masking.rst b/docs/api/indexed-data/masking.rst
@@ -1,8 +1,6 @@
 Masking
 =======
 
-.. py:module:: datacube.utils.masking
-
 .. _bit-masking:
 
 Bit Masking
@@ -13,7 +11,7 @@ Masking No Data Values
 
 .. currentmodule:: datacube.utils.masking
 
-.. automethod:: mask_invalid_data
+.. autofunction:: mask_invalid_data
 
 Masking with Bit-Flag Measurements
 ----------------------------------
@@ -40,9 +38,9 @@ Open Data Cube provides a way of describing the meanings that can be encoded
 in variables, which can then be used to give a readable method when using that
 variable.
 
-.. automethod:: describe_variable_flags
+.. autofunction:: describe_variable_flags
 
-.. automethod:: make_mask
+.. autofunction:: make_mask
 
 How to Define Meanings on Measurements
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

diff --git a/docs/installation/MIGRATION-1.8-to-1.9.rst b/docs/installation/MIGRATION-1.8-to-1.9.rst
@@ -118,7 +118,7 @@ Major Changes between 1.8.x and 1.9.x
    The postgis driver uses Alembic for managing schema migrations, so future changes to the postgis database
    schema will be much easier to roll out than in the past.
 
-   See below for more `information about migrating to the Postgis index driver<#the-new-postgis-index-driver>`_.
+   See below for more information about migrating to the :ref:`The New Postgis Index Driver`.
 
    Note that many other libraries in the ODC ecosystem may not work well with the Postgis driver at first.
 
@@ -149,7 +149,7 @@ Major Changes between 1.8.x and 1.9.x
 8. Multiple locations per dataset is now deprecated, and is not supported by the ``postgis`` index driver.
 
 .. _`odc-geo`: https://github.com/opendatacube/odc-geo
-.. _`odc-loader`: https://github.com/opendatacube/odc-loader
+.. _`odc-loader`: https://github.com/opendatacube/odc-load
 
 The New Postgis Index Driver
 ----------------------------

diff --git a/docs/installation/dataset-documents.rst b/docs/installation/dataset-documents.rst
@@ -119,7 +119,7 @@ info <image-file>``. ``shape`` is basically ``height, width`` tuple and
 encoded in a row-major order.
 
 For a full description of the eo3 dataset metadata format, refer to the
-`eo3 formal specification`_.
+eo3 `formal specification`_.