[doc] Consolidate installation guide

README.rst

@@ -26,18 +26,8 @@ BEAT_ packages through Gitlab and conda_.
 Installation
 ------------
 
-You can install this package via conda_, simply pointing to our stable or beta
-channels::
-
-  $ conda create -n bdt -c https://www.idiap.ch/software/bob/conda bob.devtools
-  # or, for beta releases:
-  $ conda create -n bdt -c https://www.idiap.ch/software/bob/conda/label/beta bob.devtools
-
-We provide packages for both 64-bit Linux and MacOS. Once installed, you can
-use these tools within the created environment like this::
-
-  $ conda activate bdt
-  (bdt) $ bdt --help
+For most up-to-date installation and usage instructions, consult the
+installation section at the `user guide`_.
 
 
 Contact
@@ -52,3 +42,4 @@ development `mailing list`_.
 .. _bob: https://www.idiap.ch/software/bob
 .. _beat: https://www.idiap.ch/software/beat
 .. _mailing list: https://www.idiap.ch/software/bob/discuss
+.. _user guide: https://www.idiap.ch/software/bob/docs/bob/bob.devtools/master/install.html

doc/index.rst

@@ -15,6 +15,7 @@ Documentation
 .. toctree::
    :maxdepth: 2
 
+   install
    release
    api
    ci

doc/install.rst

+.. vim: set fileencoding=utf-8 :
+
+.. _bob.devtools.install:
+
+
+==============
+ Installation
+==============
+
+You can install this package via conda_, simply pointing to our stable or beta
+channels::
+
+  $ conda create -n bdt -c https://www.idiap.ch/software/bob/conda bob.devtools
+  # or, for beta releases:
+  $ conda create -n bdt -c https://www.idiap.ch/software/bob/conda/label/beta bob.devtools
+
+We provide packages for both 64-bit Linux and MacOS.  Once installed, you can
+use these tools within the created environment like this::
+
+  $ conda activate bdt
+  (bdt) $ bdt --help
+
+
+
+Setup
+=====
+
+Some of the commands in the ``bdt`` command-line application require access to
+your gitlab private token, which you can pass at every iteration, or setup at
+your ``~/.python-gitlab.cfg``.  Please note that in case you don't set it up,
+it will request for your API token on-the-fly, what can be cumbersome and
+repeatitive.  Your ``~/.python-gitlab.cfg`` should roughly look like this
+(there must be an "idiap" section on it, at least):
+
+.. code-block:: ini
+
+   [global]
+   default = idiap
+   ssl_verify = true
+   timeout = 15
+
+   [idiap]
+   url = https://gitlab.idiap.ch
+   private_token = <obtain token at your settings page in gitlab>
+   api_version = 4
+
+We recommend you set ``chmod 600`` to this file to avoid prying us to read out
+your personal token. Once you have your token set up, communication should work
+transparently between these gitlab clients and the server.
+
+
+.. include:: links.rst

doc/links.rst

@@ -2,6 +2,7 @@
 
 .. Place here references to all citations in lower case
 
+.. _conda: https://conda.io
 .. _bob: https://www.idiap.ch/software/bob
 .. _shell executor: https://docs.gitlab.com/runner/executors/shell.html
 .. _gitlab runner: https://docs.gitlab.com/runner/install/osx.html

doc/release.rst

@@ -14,32 +14,6 @@ with each release.  The changelog can be autogenerated from merge-requests or
 commits in the target package.
 
 
-Setup
-=====
-
-These programs require access to your gitlab private token which you can pass
-at every iteration or setup at your ``~/.python-gitlab.cfg``. If you don't set
-it up, it will request for your API token on-the-fly, what can be cumbersome
-and repeatitive. Your ``~/.python-gitlab.cfg`` should roughly look like this
-(there must be an "idiap" section on it, at least):
-
-.. code-block:: ini
-
-   [global]
-   default = idiap
-   ssl_verify = true
-   timeout = 15
-
-   [idiap]
-   url = https://gitlab.idiap.ch
-   private_token = <obtain token at your settings page in gitlab>
-   api_version = 4
-
-We recommend you set ``chmod 600`` to this file to avoid prying us to read out
-your personal token. Once you have your token set up, communication should work
-transparently between these gitlab clients and the server.
-
-
 Usage
 =====