Merge pull request #273 from yagebu/master

docs: Some small fixes

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.
-
-.. parsed-literal::
+While we try not to break master, there are no guarantees on anything. ::
 
-    # 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.

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 ~
 

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).

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)