From b42bbc6f68ea717f11b54ae1923039900a6a3a06 Mon Sep 17 00:00:00 2001 From: Jakob Schnitzer Date: Tue, 13 Oct 2015 16:31:25 +0200 Subject: [PATCH 1/4] docs: fix code blocks --- docs/quickstart.rst | 6 +++--- docs/usage.rst | 5 ++--- 2 files changed, 5 insertions(+), 6 deletions(-) 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..efad02b5d 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -418,15 +418,14 @@ 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. -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). From fb62435fc62f6a588c6399efd263e5bde9104653 Mon Sep 17 00:00:00 2001 From: Jakob Schnitzer Date: Tue, 13 Oct 2015 16:50:27 +0200 Subject: [PATCH 2/4] docs: remove 'Additional Notes' from TOC, fix markup What's covered in the 'Additional Notes' section of the documentation hardly seems important enough to deserve its own entry in the sidebar. --- docs/usage.rst | 50 +++++++++++++++++++++++++++----------------------- 1 file changed, 27 insertions(+), 23 deletions(-) diff --git a/docs/usage.rst b/docs/usage.rst index efad02b5d..fa84b0506 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -369,54 +369,58 @@ 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. :: From 45a96fbc8d00c533cb73c7cd7ba4c743deb79aab Mon Sep 17 00:00:00 2001 From: Jakob Schnitzer Date: Tue, 13 Oct 2015 17:02:15 +0200 Subject: [PATCH 3/4] docs: change name of API section from 'Borg Backup API documentation' to 'API Documentation' It is pretty clear which software the API docs are for imho. --- setup.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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) From da926f2eb4ac00f2b5f22edfbb3bacf0fb640ce9 Mon Sep 17 00:00:00 2001 From: Jakob Schnitzer Date: Tue, 13 Oct 2015 17:25:52 +0200 Subject: [PATCH 4/4] docs: fix code blocks in installation.rst In one case removed the |project_name| and |git_url| variables to fix the display of the code block. Shouldn't be problematic, as they are not used consistently in this document anyway. Put two notes in their own nice '.. note::' blocks. --- docs/installation.rst | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) 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.