docs: add "Branch" section

docs/code/branch.py

@@ -0,0 +1,87 @@
+#!/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 tag.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
+
+""""""
+
+"""Create Branch"""
+dataset_client.create_branch("T123")
+""""""
+
+"""Branch Name Will Be Stored"""
+branch_name = dataset_client.status.branch_name
+# branch_name = "T123"
+commit_id = dataset_client.status.commit_id
+# commit_id = "xxx"
+""""""
+
+"""Create Branch Based On a Revision"""
+dataset_client.create_branch("T123", revision=commit_id_2)
+dataset_client.create_branch("T123", revision="V2")
+dataset_client.create_branch("T123", revision="main")
+""""""
+
+"""Branch Name Will Be Stored(Revision)"""
+branch_name = dataset_client.status.branch_name
+# branch_name = "T123"
+commit_id = dataset_client.status.commit_id
+# commit_id = "xxx"
+""""""
+
+"""Create Branch Based On a Former Commit"""
+dataset_client.create_branch("T1234", revision=commit_id_1)
+dataset_client.create_branch("T1234", revision="V1")
+""""""
+
+"""Branch Name Will Be Stored(Former Commit)"""
+branch_name = dataset_client.status.branch_name
+# branch_name = "T1234"
+commit_id = dataset_client.status.commit_id
+# commit_id = "xxx"
+""""""
+
+"""Create and Commit Draft"""
+dataset_client.create_draft("draft-3")
+# Do some modifications to the dataset.
+dataset_client.commit("commit-3", tag="V3")
+""""""
+
+"""List Branches"""
+branches = dataset_client.list_branches()
+""""""
+
+"""Get a Branch"""
+branch = dataset_client.get_branch("T123")
+""""""
+
+"""Delete a Branch"""
+dataset_client.delete_branch("T123")
+""""""

docs/source/features/version_control.rst

@@ -20,5 +20,7 @@ between different versions of a dataset.
    :maxdepth: 1
 
    ../version_control/draft_and_commit
+   ../version_control/branch
    ../version_control/tag
 
+

docs/source/version_control/branch.rst

@@ -0,0 +1,103 @@
+########
+ Branch
+########
+
+TensorBay supports diverging from the main line of development and continue
+to do work without messing with that main line. Like Git, the way Tensorbay branches is incredibly lightweight,
+making branching operations nearly instantaneous, and switching back and forth between branches generally just as fast.
+Tensorbay encourages workflows that branch often, even multiple times in a day.
+
+Before operating branches, a dataset client instance with existing commit is needed.
+
+.. literalinclude:: ../../../docs/code/branch.py
+      :language: python
+      :start-after: """Authorize a Dataset Client Instance"""
+      :end-before: """"""
+
+***************
+ Create Branch
+***************
+
+Create Branch on the Current Commit
+===================================
+
+TensorBay SDK supports creating the branch straightforwardly, which is based on the current commit.
+
+.. literalinclude:: ../../../docs/code/branch.py
+      :language: python
+      :start-after: """Create Branch"""
+      :end-before: """"""
+
+Then the dataset client will storage the branch name. "main" is the default branch, it will be created when init the
+dataset.
+
+.. literalinclude:: ../../../docs/code/branch.py
+      :language: python
+      :start-after: """Branch Name Will Be Stored"""
+      :end-before: """"""
+
+Create Branch Based On a Revision
+=================================
+
+Also, creating a branch based on a revision is allowed.
+
+.. literalinclude:: ../../../docs/code/branch.py
+      :language: python
+      :start-after: """Create Branch Based On a Revision"""
+      :end-before: """"""
+
+The dataset client will checkout to the branch. The stored commit id is from the commit which the branch points to.
+
+.. literalinclude:: ../../../docs/code/branch.py
+      :language: python
+      :start-after: """Branch Name Will Be Stored(Revision)"""
+      :end-before: """"""
+
+Specially, creating a branch based on a former commit is permitted.
+
+.. literalinclude:: ../../../docs/code/branch.py
+      :language: python
+      :start-after: """Create Branch Based On a Former Commit"""
+      :end-before: """"""
+
+Similarly, the dataset client will checkout to the branch.
+
+.. literalinclude:: ../../../docs/code/branch.py
+      :language: python
+      :start-after: """Branch Name Will Be Stored(Former Commit)"""
+      :end-before: """"""
+
+Then, through creating and committing the draft
+based on the branch, diverging from the current line of development can be realized.
+
+.. literalinclude:: ../../../docs/code/branch.py
+      :language: python
+      :start-after: """Create and Commit Draft"""
+      :end-before: """"""
+
+***************
+ List Branches
+***************
+
+.. literalinclude:: ../../../docs/code/branch.py
+      :language: python
+      :start-after: """List Branches"""
+      :end-before: """"""
+
+************
+ Get Branch
+************
+
+.. literalinclude:: ../../../docs/code/branch.py
+      :language: python
+      :start-after: """Get a Branch"""
+      :end-before: """"""
+
+***************
+ Delete Branch
+***************
+
+.. literalinclude:: ../../../docs/code/branch.py
+      :language: python
+      :start-after: """Delete a Branch"""
+      :end-before: """"""