docs: add docs for diff

PR Closed: #934

docs/code/diff.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+#
+# Copyright 2021 Graviti. Licensed under MIT License.
+#
+
+# pylint: disable=wrong-import-position
+# pylint: disable=wrong-import-order
+# pylint: disable=not-callable
+# pylint: disable=ungrouped-imports
+# pylint: disable=import-error
+# pylint: disable=pointless-string-statement
+# pylint: disable=invalid-name
+
+
+"""This file includes the python code of diff.rst."""
+
+"""Authorize a Dataset Client Instance"""
+from tensorbay import GAS
+
+ACCESS_KEY = "Accesskey-*****"
+gas = GAS(ACCESS_KEY)
+dataset_client = gas.create_dataset("DatasetName")
+dataset_client.create_draft("draft-1")
+# Add some data to the dataset.
+dataset_client.commit("commit-1", tag="V1")
+commit_id_1 = dataset_client.status.commit_id
+
+dataset_client.create_draft("draft-2")
+# Do some modifications to the dataset.
+dataset_client.commit("commit-2", tag="V2")
+commit_id_2 = dataset_client.status.commit_id
+
+dataset_client.create_draft("draft-3")
+draft_number_3 = dataset_client.status.draft_number
+head = ""
+
+""""""
+
+"""Get Diff"""
+diff = dataset_client.get_diff(head=head)
+""""""
+
+"""Get Diff on Commit"""
+diff = dataset_client.get_diff(head="3bc35d806e0347d08fc23564b82737dc")
+""""""
+
+"""Get Diff on Draft"""
+diff = dataset_client.get_diff(head=1)
+""""""

docs/source/api/client/client_module.rst

@@ -14,3 +14,4 @@ tensorbay.client
    status
    struct
    version
+   diff

docs/source/api/client/diff.rst

@@ -0,0 +1,6 @@
+tensorbay.client.diff
+======================
+
+.. automodule:: tensorbay.client.diff
+   :members:
+   :show-inheritance:

docs/source/features/version_control.rst

@@ -22,5 +22,7 @@ between different versions of a dataset.
    ../version_control/draft_and_commit
    ../version_control/branch
    ../version_control/tag
+   ../version_control/diff
+
 
 

docs/source/reference/glossary.rst

@@ -16,6 +16,17 @@ For the usage of accesskey via Tensorbay SDK or CLI,
 please see :ref:`SDK authorization <quick_start/getting_started_with_tensorbay:Authorize a Client Instance>`
 or :ref:`CLI configration <tensorbay_cli/getting_started_with_cli:Authentication>`.
 
+basehead
+========
+The basehead is the string for recording the two relative versions(commits or drafts) in the
+format of "base...head".
+
+The basehead param is comprised of two parts: base and head. Both must be :ref:`reference/glossary:revision`
+or draft number in dataset. The terms "head" and "base" are used as they normally are in Git.
+
+The head is the version which changes are on.
+The base is the version of which these changes are based.
+
 branch
 ======
 
@@ -123,6 +134,12 @@ The corresponding class of dataset is :class:`~tensorbay.dataset.dataset.Dataset
 
 See :ref:`reference/dataset_structure:Dataset Structure` for more details.
 
+diff
+====
+
+TensorBay supports showing the status difference of the relative
+resource between commits or drafts in the form of diff.
+
 draft
 =====
 

docs/source/version_control/diff.rst

@@ -0,0 +1,88 @@
+######
+ Diff
+######
+
+TensorBay supports showing changes between commits or drafts.
+
+Before operating the :ref:`reference/glossary:diff`, a dataset client instance with commits is needed.
+See more details in :ref:`version_control/draft_and_commit:Draft and Commit`
+
+**********
+ Get Diff
+**********
+
+TensorBay SDK allows getting the dataset :ref:`reference/glossary:diff`
+through :ref:`reference/glossary:basehead`. Currently, only obtaining the :ref:`reference/glossary:diff`
+between the head and its parent commit is supported; that is, the head is the given version(commit or draft) while the
+base is parent commit of the head.
+
+.. literalinclude:: ../../../docs/code/diff.py
+      :language: python
+      :start-after: """Get Diff"""
+      :end-before: """"""
+
+The type of the head indicates the version status: ``string`` for commit, ``int`` for draft.
+
+
+Get Diff on Revision
+====================
+
+For example, the following diff records the difference between the commit whose id is ``"3bc35d806e0347d08fc23564b82737dc"``
+and its parent commit.
+
+.. literalinclude:: ../../../docs/code/diff.py
+      :language: python
+      :start-after: """Get Diff on Commit"""
+      :end-before: """"""
+
+Get Diff on Draft Number
+========================
+
+For example, the following diff records the difference between the draft whose draft number is ``1``
+and its parent commit.
+
+.. literalinclude:: ../../../docs/code/diff.py
+      :language: python
+      :start-after: """Get Diff on Draft"""
+      :end-before: """"""
+
+Diff Object
+===========
+
+The structure of the returning :class:`~tensorbay.client.diff.DatasetDiff` looks like::
+
+   dataset_diff
+   ├── segment_diff
+   │   ├── action
+   │   │   └── <str>
+   │   ├── data_diff
+   │   │   ├── file_diff
+   │   │   │   └── action
+   │   │   │       └── <str>
+   │   │   └── label_diff
+   │   │       └── action
+   │   │           └── <str>
+   │   └── ...
+   ├── segment_diff
+   │   ├── action
+   │   │   └── <str>
+   │   ├── data_diff
+   │   │   ├── file_diff
+   │   │   │   └── action
+   │   │   │       └── <str>
+   │   │   └── label_diff
+   │   │       └── action
+   │   │           └── <str>
+   │   └── ...
+   └── ...
+
+The :class:`~tensorbay.client.diff.DatasetDiff` is a list which is composed of :class:`~tensorbay.client.diff.SegmentDiff`
+recording the changes of the segment. The :class:`~tensorbay.client.diff.SegmentDiff` is a lazy-load sequence
+which is composed of :class:`~tensorbay.client.diff.DataDiff` recording the changes of data.
+
+The attribute "action" represents the status difference of the relative resource. It is an enum which includes:
+
+- unmodify
+- add
+- delete
+- modify

tensorbay/client/diff.py

@@ -141,15 +141,15 @@ def loads(cls: Type[_T], contents: Dict[str, Any]) -> _T:
             contents: A dict containing all the brief diff information of data::
 
                      {
-                        "remotePath": <str>,
-                        "action": <str>,
-                        "file": {
-                            "action": <str>
-                        }
-                        "label": {
-                            "action": <str>
-                        }
-                    }
+                         "remotePath": <str>,
+                         "action": <str>,
+                         "file": {
+                             "action": <str>
+                         },
+                         "label": {
+                             "action": <str>
+                         }
+                     }
 
         Returns:
             A :class:`DataDiff` instance containing all the information in the given contents.
@@ -164,15 +164,15 @@ def dumps(self) -> Dict[str, Any]:
             A dict containing all the brief diff information of data::
 
                  {
-                    "remotePath": <str>,
-                    "action": <str>,
-                    "file": {
-                        "action": <str>
-                    }
-                    "label": {
-                        "action": <str>
-                    }
-                }
+                     "remotePath": <str>,
+                     "action": <str>,
+                     "file": {
+                         "action": <str>
+                     },
+                     "label": {
+                         "action": <str>
+                     }
+                 }
 
         """
         return self._dumps()