docs: add docs for Group Import/Export API

nejch · nejch · commit 8c3d744ec639 · 2020-04-05T23:39:19.000+02:00
diff --git a/docs/gl_objects/groups.rst b/docs/gl_objects/groups.rst
@@ -67,6 +67,62 @@ Remove a group::
     # or
     group.delete()
 
+Import / Export
+===============
+
+You can export groups from gitlab, and re-import them to create new groups.
+
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.GroupExport`
+  + :class:`gitlab.v4.objects.GroupExportManager`
+  + :attr:`gitlab.v4.objects.Group.exports`
+  + :class:`gitlab.v4.objects.GroupImport`
+  + :class:`gitlab.v4.objects.GroupImportManager`
+  + :attr:`gitlab.v4.objects.Group.imports`
+  + :attr:`gitlab.v4.objects.GroupManager.import_group`
+
+* GitLab API: https://docs.gitlab.com/ce/api/group_import_export.html
+
+Examples
+--------
+
+A group export is an asynchronous operation. To retrieve the archive
+generated by GitLab you need to:
+
+#. Create an export using the API
+#. Wait for the export to be done
+#. Download the result
+
+.. warning::
+
+   Unlike the Project Export API, GitLab does not provide an export_status
+   for Group Exports. It is up to the user to ensure the export is finished.
+
+   However, Group Exports only contain metadata, so they are much faster
+   than Project Exports.
+
+::
+
+    # Create the export
+    group = gl.groups.get(my_group)
+    export = group.exports.create()
+
+    # Wait for the export to finish
+    time.sleep(3)
+
+    # Download the result
+    with open('/tmp/export.tgz', 'wb') as f:
+        export.download(streamed=True, action=f.write)
+
+Import the group::
+
+    with open('/tmp/export.tgz', 'rb') as f:
+        gl.groups.import_group(f, path='imported-group', name="Imported Group")
+
 Subgroups
 =========
 
