docs: move config files + runtime dir doc to new configuration/preface

docs/configuration.rst

@@ -7,6 +7,7 @@ Configuration
 
 .. toctree::
 
+    configuration/preface
     configuration/jobs
     configuration/transports
     configuration/map_filter_syntax

docs/configuration/logging.rst

@@ -31,6 +31,8 @@ Check out :sampleconf:`random/logging.yml` for an example on how to configure mu
     The **first outlet is special**: if an error writing to any outlet occurs, the first outlet receives the error and can print it.
     Thus, the first outlet must be the one that always works and does not block, e.g. ``stdout``, which is the default.
 
+.. _logging-default-config:
+
 Default Configuration
 ---------------------
 

docs/configuration/misc.rst

@@ -13,10 +13,9 @@ zrepl daemon creates various UNIX sockets to allow communicating with it:
 
 There is no further authentication on these sockets.
 Therefore we have to make sure they can only be created and accessed by ``zrepl daemon``.
-
 In fact, ``zrepl daemon`` will not bind a socket to a path in a directory that is world-accessible.
 
-The directories can be configured in the main configuration file:
+The directories can be configured in the main configuration file, the defaults are provided below:
 
 ::
 

docs/configuration/preface.rst

@@ -0,0 +1,33 @@
+
+.. _configuration_preface:
+
+=======
+Preface
+=======
+
+-----------------------
+Configuration File Path
+-----------------------
+
+zrepl searches for its main configuration file in the following locations (in that order):
+
+* If set, the location specified via the global ``--config`` flag
+* ``/etc/zrepl/zrepl.yml``
+* ``/usr/local/etc/zrepl/zrepl.yml``
+
+The examples in the :ref:`tutorial` or the ``cmd/sampleconf`` directory should provide a good starting point.
+
+-------------------
+Runtime Directories
+-------------------
+
+zrepl requires runtime directories for various UNIX sockets --- they are documented in the :ref:`config file<conf-runtime-directories>`.
+Your package maintainer / init script should take care of creating them.
+Alternatively, for default settings, the following should to the trick.
+
+::
+
+    mkdir -p /var/run/zrepl/stdinserver
+    chmod -R 0700 /var/run/zrepl
+
+

docs/installation.rst

@@ -78,56 +78,11 @@ Build results are located in the ``artifacts/`` directory.
 
 .. _mainconfigfile:
 
-Configuration Files
--------------------
+What next?
+----------
 
-zrepl searches for its main configuration file in the following locations (in that order):
+Read the :ref:`configuration chapter<configuration_toc>` and optionally create the :ref:`runtime directories <configuration_preface>`.
+Afterwards, continue with the :ref:`usage chapter<usage>`.
 
-* ``/etc/zrepl/zrepl.yml``
-* ``/usr/local/etc/zrepl/zrepl.yml``
+**Reminder**: If you want a quick introduction, please read the :ref:`tutorial`.
 
-Alternatively, use CLI flags to specify a config location.
-Copy a config from the :ref:`tutorial` or the ``cmd/sampleconf`` directory to one of these locations and customize it to your setup.
-
-Runtime Directories
--------------------
-
-zrepl requires ephemeral runtime directories where control sockets, etc are placed.
-Refer to the :ref:`configuration documentation <conf-runtime-directories>` for more information.
-
-When installing from a package, the package maintainer should have taken care of setting them up through the init system.
-Alternatively, for default settings, the following should to the trick.
-
-::
-
-    mkdir -p /var/run/zrepl/stdinserver
-    chmod -R 0700 /var/run/zrepl
-
-
-Running the Daemon
-------------------
-
-All actual work zrepl does is performed by a daemon process.
-Logging is configurable via the config file. Please refer to the :ref:`logging documention <logging>`.
-
-When installating from a package, the package maintainer should have provided an init script / systemd.service file.
-You should thus be able to start zrepl daemon using your init system.
-
-Alternatively, or for running zrepl in the foreground, simply execute ``zrepl daemon``.
-Note that you won't see any output unless you configure :ref:`stdout logging outlet <logging-outlet-stdout>`.
-
-.. ATTENTION::
-
-    Make sure to actually monitor the error level output of zrepl: some configuration errors will not make the daemon exit.
-
-    Example: if the daemon cannot create the :ref:`transport-ssh+stdinserver` sockets in the runtime directory,
-    it will emit an error message but not exit because other tasks such as periodic snapshots & pruning are of equal importance.
-
-.. _install-restarting:
-
-Restarting
-~~~~~~~~~~
-
-The daemon handles SIGINT and SIGTERM for graceful shutdown.
-Graceful shutdown means at worst that a job will not be rescheduled for the next interval.
-The daemon exits as soon as all jobs have reported shut down.

docs/tutorial.rst

@@ -153,7 +153,7 @@ Apply Configuration Changes
 ---------------------------
 
 We need to restart the zrepl daemon on **both** ``app-srv`` and ``backup-srv``.
-This is :ref:`OS-specific <install-restarting>`.
+This is :ref:`OS-specific <usage-zrepl-daemon-restarting>`.
 
 Watch it Work
 -------------

docs/usage.rst

@@ -1,3 +1,5 @@
+.. _usage:
+
 *****
 Usage
 *****
@@ -26,3 +28,33 @@ CLI Overview
     * - ``zrepl stdinserver``
       - see :ref:`transport-ssh+stdinserver`
 
+.. _usage-zrepl-daemon:
+
+============
+zrepl daemon
+============
+
+All actual work zrepl does is performed by a daemon process.
+Logging is configurable via the config file. Please refer to the :ref:`logging documention <logging>`.
+
+When installating from a package, the package maintainer should have provided an init script / systemd.service file.
+You should thus be able to start zrepl daemon using your init system.
+
+Alternatively, or for running zrepl in the foreground, simply execute ``zrepl daemon``.
+Note that you won't see much output with the :ref:`default logging configuration<logging-default-config>`:
+
+.. ATTENTION::
+
+    Make sure to actually monitor the error level output of zrepl: some configuration errors will not make the daemon exit.
+
+    Example: if the daemon cannot create the :ref:`transport-ssh+stdinserver` sockets in the runtime directory,
+    it will emit an error message but not exit because other tasks such as periodic snapshots & pruning are of equal importance.
+
+.. _usage-zrepl-daemon-restarting:
+
+Restarting
+~~~~~~~~~~
+
+The daemon handles SIGINT and SIGTERM for graceful shutdown.
+Graceful shutdown means at worst that a job will not be rescheduled for the next interval.
+The daemon exits as soon as all jobs have reported shut down.