diff --git a/docs/installation.rst b/docs/installation.rst index edfb0edc0..77cd99aad 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -91,7 +91,7 @@ Check https://github.com/borgbackup/borg/releases for available binaries. Debian Jessie / Ubuntu 14.04 preparations (git/pypi) ---------------------------------------------------- -.. parsed-literal:: +:: # Python 3.x (>= 3.2) + Headers, Py Package Installer, VirtualEnv apt-get install python3 python3-dev python3-pip python-virtualenv @@ -121,7 +121,7 @@ Debian Jessie / Ubuntu 14.04 preparations (git/pypi) Korora / Fedora 21 preparations (git/pypi) ------------------------------------------ -.. parsed-literal:: +:: # Python 3.x (>= 3.2) + Headers, Py Package Installer, VirtualEnv sudo dnf install python3 python3-devel python3-pip python3-virtualenv @@ -178,9 +178,7 @@ In case that creation of the virtual env fails, try deleting this file: Installation (pypi) ------------------- -This uses the latest (source package) release from PyPi. - -.. parsed-literal:: +This uses the latest (source package) release from PyPi. :: virtualenv --python=python3 borg-env source borg-env/bin/activate # always before using! @@ -190,19 +188,17 @@ This uses the latest (source package) release from PyPi. # 0.41 and 0.41.1 have unicode issues at install time pip install borgbackup -Note: we install into a virtual environment here, but this is not a requirement. +.. note:: We install into a virtual environment here, but this is not a requirement. Installation (git) ------------------ This uses latest, unreleased development code from git. -While we try not to break master, there are no guarantees on anything. +While we try not to break master, there are no guarantees on anything. :: -.. parsed-literal:: - - # get |project_name| from github, install it - git clone |git_url| + # get borg from github + git clone https://github.com/borgbackup/borg.git virtualenv --python=python3 borg-env source borg-env/bin/activate # always before using! @@ -218,4 +214,4 @@ While we try not to break master, there are no guarantees on anything. # optional: run all the tests, on all supported Python versions fakeroot -u tox -Note: as a developer or power user, you always want to use a virtual environment. +.. note:: As a developer or power user, you always want to use a virtual environment. diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 32218fc67..9ad86d5e2 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -100,17 +100,17 @@ Backup compression Default is no compression, but we support different methods with high speed or high compression: -If you have a quick repo storage and you want a little compression: +If you have a quick repo storage and you want a little compression: :: $ borg create --compression lz4 /mnt/backup::repo ~ If you have a medium fast repo storage and you want a bit more compression (N=0..9, -0 means no compression, 9 means high compression): +0 means no compression, 9 means high compression): :: $ borg create --compression zlib,N /mnt/backup::repo ~ If you have a very slow repo storage and you want high compression (N=0..9, 0 means -low compression, 9 means high compression): +low compression, 9 means high compression): :: $ borg create --compression lzma,N /mnt/backup::repo ~ diff --git a/docs/usage.rst b/docs/usage.rst index 80f3eaa2f..fa84b0506 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -369,64 +369,67 @@ Examples Additional Notes -================ +---------------- Here are misc. notes about topics that are maybe not covered in enough detail in the usage section. --read-special --------------- +~~~~~~~~~~~~~~ -The option --read-special is not intended for normal, filesystem-level (full or +The option ``--read-special`` is not intended for normal, filesystem-level (full or partly-recursive) backups. You only give this option if you want to do something -rather ... special - and if you have hand-picked some files that you want to treat +rather ... special -- and if you have hand-picked some files that you want to treat that way. -`borg create --read-special` will open all files without doing any special treatment -according to the file type (the only exception here are directories: they will be -recursed into). Just imagine what happens if you do `cat filename` - the content -you will see there is what borg will backup for that filename. +``borg create --read-special`` will open all files without doing any special +treatment according to the file type (the only exception here are directories: +they will be recursed into). Just imagine what happens if you do ``cat +filename`` --- the content you will see there is what borg will backup for that +filename. So, for example, symlinks will be followed, block device content will be read, named pipes / UNIX domain sockets will be read. -You need to be careful with what you give as filename when using --read-special, -e.g. if you give /dev/zero, your backup will never terminate. +You need to be careful with what you give as filename when using ``--read-special``, +e.g. if you give ``/dev/zero``, your backup will never terminate. -The given files' metadata is saved as it would be saved without --read-special -(e.g. its name, its size [might be 0], its mode, etc.) - but additionally, also -the content read from it will be saved for it. +The given files' metadata is saved as it would be saved without +``--read-special`` (e.g. its name, its size [might be 0], its mode, etc.) - but +additionally, also the content read from it will be saved for it. -Restoring such files' content is currently only supported one at a time via --stdout -option (and you have to redirect stdout to where ever it shall go, maybe directly -into an existing device file of your choice or indirectly via dd). +Restoring such files' content is currently only supported one at a time via +``--stdout`` option (and you have to redirect stdout to where ever it shall go, +maybe directly into an existing device file of your choice or indirectly via +``dd``). Example ~~~~~~~ Imagine you have made some snapshots of logical volumes (LVs) you want to backup. -Note: For some scenarios, this is a good method to get "crash-like" consistency -(I call it crash-like because it is the same as you would get if you just hit the -reset button or your machine would abrubtly and completely crash). -This is better than no consistency at all and a good method for some use cases, -but likely not good enough if you have databases running. +.. note:: + + For some scenarios, this is a good method to get "crash-like" consistency + (I call it crash-like because it is the same as you would get if you just + hit the reset button or your machine would abrubtly and completely crash). + This is better than no consistency at all and a good method for some use + cases, but likely not good enough if you have databases running. Then you create a backup archive of all these snapshots. The backup process will see a "frozen" state of the logical volumes, while the processes working in the original volumes continue changing the data stored there. -You also add the output of `lvdisplay` to your backup, so you can see the LV sizes -in case you ever need to recreate and restore them. +You also add the output of ``lvdisplay`` to your backup, so you can see the LV +sizes in case you ever need to recreate and restore them. -After the backup has completed, you remove the snapshots again. +After the backup has completed, you remove the snapshots again. :: -:: $ # create snapshots here $ lvdisplay > lvdisplay.txt $ borg create --read-special /mnt/backup::repo lvdisplay.txt /dev/vg0/*-snapshot $ # remove snapshots here -Now, let's see how to restore some LVs from such a backup. +Now, let's see how to restore some LVs from such a backup. :: $ borg extract /mnt/backup::repo lvdisplay.txt $ # create empty LVs with correct sizes here (look into lvdisplay.txt). diff --git a/setup.py b/setup.py index e2fce2823..5c3e31d8f 100644 --- a/setup.py +++ b/setup.py @@ -184,8 +184,8 @@ class build_api(Command): print("auto-generating API documentation") with open("docs/api.rst", "w") as doc: doc.write(""" -Borg Backup API documentation -============================= +API Documentation +================= """) for mod in glob('borg/*.py') + glob('borg/*.pyx'): print("examining module %s" % mod)