[DOC] Add admin and user documentation for share revert to snapshot

This patch adds the admin and user documentation for share revert to
the latest available snapshot.

Change-Id: Id35b99fdb47bb9de38f42034818fb4a29370bf36
Closes-Bug: #1657322

doc/source/admin/index.rst

@@ -55,6 +55,7 @@ deployment.
    shared-file-systems-networking.rst
    shared-file-systems-troubleshoot.rst
    shared-file-systems-upgrades.rst
+   shared-file-systems-share-revert-to-snapshot.rst
    share_back_ends_feature_support_mapping
    capabilities_and_extra_specs
    group_capabilities_and_extra_specs

doc/source/admin/shared-file-systems-share-revert-to-snapshot.rst

@@ -0,0 +1,39 @@
+.. _shared_file_systems_share_revert_to_snapshot:
+
+========================
+Share revert to snapshot
+========================
+
+To revert a share to the latest available snapshot, use the
+:command:`manila revert-to-snapshot`.
+
+.. note::
+    - In order to use this feature, the available backend in your deployment
+      must have support for it. The list of backends that support this feature
+      in the manila can be found in the :doc:`share_back_ends_feature_support_mapping`.
+    - This feature is only available in API version 2.27 and beyond. To create
+      shares that are revertible, the share type used must contain the extra-spec
+      ``revert_to_snapshot_support`` set to ``True``. The default value for
+      this is ``False``.
+    - The revert operation can only be performed to the most recent available
+      snapshot of the share known to manila. If revert to an earlier snapshot
+      is desired, later snapshots must explicitly be deleted. In order to
+      determine the most recent snapshot, the ``created_at`` field on the
+      snapshot object is used.
+
+While reverting, the share is in ``reverting`` status and the snapshot is in
+``restoring`` status. After a successful restoration, the share and snapshot
+states will again be set to ``available``. If the restoration fails
+the share will be set to ``reverting_error`` state and the snapshot will be
+set to ``available``.
+
+When a replicated share is reverted, the share becomes ready to be used only
+when all ``active`` replicas have been reverted. All secondary replicas will
+remain in ``out-of-sync`` state until they are consistent with the ``active``
+replicas.
+
+To revert a share to a snapshot, run:
+
+.. code-block:: console
+
+   $ manila revert-to-snapshot 14ee8575-aac2-44af-8392-d9c9d344f392

doc/source/user/create-and-manage-shares.rst

@@ -877,3 +877,22 @@ Share metadata
   .. code-block:: console
 
      $ manila metadata myshare unset year_started
+
+Share revert to snapshot
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Share revert to snapshot
+
+  .. note::
+
+   -  To revert a share to its snapshot, the share type of the share must
+      contain the capability extra-spec ``revert_to_snapshot_support=True``.
+   -  The revert operation can only be performed to the most recent available
+      snapshot of the share known to manila. If revert to an earlier snapshot
+      is desired, later snapshots must explicitly be deleted.
+
+  .. code-block:: console
+
+     $ manila revert-to-snapshot mysnapshot
+
+