From d75fc6c28b57a4ec34b9e41d6058e3788a72199d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?=
 <marmarek@invisiblethingslab.com>
Date: Fri, 21 Apr 2017 19:18:11 +0200
Subject: [PATCH] backup: add a little more usage info, include docs in main
 index

---
 doc/index.rst        |  1 +
 doc/qubes-backup.rst |  8 ++++++++
 qubes/backup.py      | 25 +++++++++++++++++++++++++
 3 files changed, 34 insertions(+)
 create mode 100644 doc/qubes-backup.rst

diff --git a/doc/index.rst b/doc/index.rst
index 3ace08e2..a9c95a9f 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -21,6 +21,7 @@ manpages and API documentation. For primary user documentation, see
    qubes-log
    qubes-mgmt
    qubes-policy
+   qubes-backup
    qubes-tools/index
    qubes-tests
    qubes-dochelpers
diff --git a/doc/qubes-backup.rst b/doc/qubes-backup.rst
new file mode 100644
index 00000000..d77437e5
--- /dev/null
+++ b/doc/qubes-backup.rst
@@ -0,0 +1,8 @@
+:py:mod:`qubes.backup` -- Backup
+================================
+
+.. automodule:: qubes.backup
+   :members:
+   :show-inheritance:
+
+.. vim: ts=3 sw=3 et
diff --git a/qubes/backup.py b/qubes/backup.py
index 1d73cc98..1a26221a 100644
--- a/qubes/backup.py
+++ b/qubes/backup.py
@@ -76,6 +76,9 @@ class BackupCanceledError(qubes.exc.QubesException):
 
 
 class BackupHeader(object):
+    '''Structure describing backup-header file included as the first file in
+    backup archive
+    '''
     header_keys = {
         'version': 'version',
         'encrypted': 'encrypted',
@@ -283,6 +286,27 @@ def launch_scrypt(action, input_name, output_name, passphrase):
 
 
 class Backup(object):
+    '''Backup operation manager. Usage:
+
+    >>> app = qubes.Qubes()
+    >>> # optional - you can use 'None' to use default list (based on
+    >>> #  vm.include_in_backups property)
+    >>> vms = [app.domains[name] for name in ['my-vm1', 'my-vm2', 'my-vm3']]
+    >>> exclude_vms = []
+    >>> options = {
+    >>>     'encrypted': True,
+    >>>     'compressed': True,
+    >>>     'passphrase': 'This is very weak backup passphrase',
+    >>>     'target_vm': app.domains['sys-usb'],
+    >>>     'target_dir': '/media/disk',
+    >>> }
+    >>> backup_op = Backup(app, vms, exclude_vms, **options)
+    >>> print(backup_op.get_backup_summary())
+    >>> backup_op.backup_do()
+
+    See attributes of this object for all available options.
+
+    '''
     class FileToBackup(object):
         def __init__(self, file_path, subdir=None, name=None):
             sz = qubes.storage.file.get_disk_usage(file_path)
@@ -1404,6 +1428,7 @@ class BackupRestoreOptions(object):
 
 class BackupRestore(object):
     """Usage:
+
     >>> restore_op = BackupRestore(...)
     >>> # adjust restore_op.options here
     >>> restore_info = restore_op.get_restore_info()