From 9f8700e3831d8aa445ff86fa98f1b5ea659fbb89 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= Date: Sat, 14 Nov 2015 21:03:38 -0500 Subject: [PATCH 1/3] restructure install page headings do not repeat "installation" all the time, and regroup git and pip under "from source" also link to the sections in the summary --- docs/installation.rst | 56 ++++++++++++++++++++++++++----------------- 1 file changed, 34 insertions(+), 22 deletions(-) diff --git a/docs/installation.rst b/docs/installation.rst index efe8dadbc..625b1cbf7 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -6,18 +6,23 @@ Installation There are different ways to install |project_name|: -- **distribution package** - easy and fast if a package is available for your - Linux/BSD distribution. -- **PyInstaller binary** - easy and fast, we provide a ready-to-use binary file +- :ref:`distribution-package` - easy and fast if a package is + available from your operating system. +- :ref:`pyinstaller-binary` - easy and fast, we provide a ready-to-use binary file that comes bundled with all dependencies. -- **pip** - installing a source package with pip needs more installation steps - and requires all dependencies with development headers and a compiler. -- **git** - for developers and power users who want to have the latest code or - use revision control (each release is tagged). +- :ref:`source-install`, either: + - :ref:`pip-installation` - installing a source package with pip needs + more installation steps and requires all dependencies with + development headers and a compiler. + - :ref:`git-installation` - for developers and power users who want to + have the latest code or use revision control (each release is + tagged). -Installation (Distribution Package) ------------------------------------ +.. _distribution-package: + +Distribution Package +-------------------- Some Linux and BSD distributions might offer a ready-to-use ``borgbackup`` package which can be installed with the package manager. As |project_name| is @@ -32,9 +37,10 @@ and compare that to our latest release and review the :doc:`changes`. .. _AUR: https://aur.archlinux.org/packages/borgbackup/ +.. _pyinstaller-binary: -Installation (PyInstaller Binary) ---------------------------------- +PyInstaller Binary +------------------ The |project_name| binary is available on the releases_ page for the following platforms: @@ -50,10 +56,15 @@ version. .. _releases: https://github.com/borgbackup/borg/releases -Installing the Dependencies ---------------------------- +.. _source-install: -To install |project_name| from a source package, you have to install the +From source +----------- + +Dependencies +~~~~~~~~~~~~ + +To install |project_name| from a source package (including pip), you have to install the following dependencies first: * `Python 3`_ >= 3.2.2. Even though Python 3 is not the default Python version on @@ -75,7 +86,7 @@ After you have installed the dependencies, you can proceed with steps outlined under :ref:`pip-installation`. Debian / Ubuntu -~~~~~~~~~~~~~~~ ++++++++++++++++ Install the dependencies with development headers:: @@ -91,7 +102,7 @@ Ubuntu this means your user is not in the ``fuse`` group. Add yourself to that group, log out and log in again. Fedora / Korora -~~~~~~~~~~~~~~~ ++++++++++++++++ Install the dependencies with development headers:: @@ -103,7 +114,7 @@ Install the dependencies with development headers:: Mac OS X -~~~~~~~~ +++++++++ Assuming you have installed homebrew_, the following steps will install all the dependencies:: @@ -117,7 +128,7 @@ FUSE for OS X, which is available as a pre-release_. .. _pre-release: https://github.com/osxfuse/osxfuse/releases Cygwin -~~~~~~ +++++++ .. note:: Running under Cygwin is experimental and has only been tested with Cygwin @@ -144,8 +155,8 @@ In case the creation of the virtual environment fails, try deleting this file:: .. _pip-installation: -Installation (pip) ------------------- +From pip +~~~~~~~~ Virtualenv_ can be used to build and install |project_name| without affecting the system Python or requiring root access. Using a virtual environment is @@ -172,9 +183,10 @@ activating your virtual environment:: pip install -U borgbackup +.. _git-installation: -Installation (git) ------------------- +From git +~~~~~~~~ This uses latest, unreleased development code from git. While we try not to break master, there are no guarantees on anything. :: From a8d2c18fee6659a4992d444ecc838d9d8c44fc73 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= Date: Sat, 14 Nov 2015 21:07:16 -0500 Subject: [PATCH 2/3] split packaging meta-info in a separate paragraph and link to github --- docs/installation.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/installation.rst b/docs/installation.rst index 625b1cbf7..c8db6fae2 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -27,16 +27,19 @@ Distribution Package Some Linux and BSD distributions might offer a ready-to-use ``borgbackup`` package which can be installed with the package manager. As |project_name| is still a young project, such a package might be not available for your system -yet. Please ask package maintainers to build a package or, if you can package / -submit it yourself, please help us with that! +yet. * On **Arch Linux**, there is a package available in the AUR_. +.. _AUR: https://aur.archlinux.org/packages/borgbackup/ + +Please ask package maintainers to build a package or, if you can package / +submit it yourself, please help us with that! See :issue:`105` on +github to followup on packaging efforts. + If a package is available, it might be interesting to check its version and compare that to our latest release and review the :doc:`changes`. -.. _AUR: https://aur.archlinux.org/packages/borgbackup/ - .. _pyinstaller-binary: PyInstaller Binary From aa4c76872c3e58ecb3d596069cc381352972a5ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antoine=20Beaupr=C3=A9?= Date: Sat, 14 Nov 2015 21:08:28 -0500 Subject: [PATCH 3/3] move pyinstaller mention out of heading pyinstaller probably means nothing for most people, while standalone binary is more meaningful --- docs/installation.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/installation.rst b/docs/installation.rst index c8db6fae2..2506d4ec2 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -42,11 +42,11 @@ and compare that to our latest release and review the :doc:`changes`. .. _pyinstaller-binary: -PyInstaller Binary ------------------- +Standalone binary +----------------- -The |project_name| binary is available on the releases_ page for the following -platforms: +|project_name| binaries (generated with `pyinstaller`_) are available +on the releases_ page for the following platforms: * **Linux**: glibc >= 2.13 (ok for most supported Linux releases) * **Mac OS X**: 10.10 (unknown whether it works for older releases) @@ -57,6 +57,7 @@ them into a directory in your ``PATH`` and then you can run ``borg``. If a new version is released, you will have to manually download it and replace the old version. +.. _pyinstaller: http://www.pyinstaller.org .. _releases: https://github.com/borgbackup/borg/releases .. _source-install: