Optimized documentation.

Related to debops/docs#140

defaults/main.yml

@@ -104,7 +104,7 @@ preseed__release: '{{ ansible_distribution_release }}'
 
 # .. envvar:: preseed__configs
 #
-# List of Preseed definitions. See :ref:`preseed__configs` for more details.
+# List of Preseed definitions. See :ref:`preseed__section_detailed_configs` for more details.
 preseed__configs:
 
   # Debian - default configuration which will ask the user for disk
@@ -211,7 +211,7 @@ preseed__sudo: True
 # .. envvar:: preseed__sudo_group
 #
 # Name of the system group which will be configured with passwordless ``sudo``
-# access. By default it's the first group set in ``preseed__admin_groups``.
+# access. By default it's the first group set in :any:`preseed__admin_groups`.
 preseed__sudo_group: '{{ preseed__admin_groups[0] }}'
 
 
@@ -276,11 +276,13 @@ preseed__debian_mirror_hostname: 'httpredir.debian.org'
 # Subdirectory on the HTTP mirror which holds the Debian repository.
 preseed__debian_mirror_directory: '/debian'
 
+
 # .. envvar:: preseed__debian_mirror_proxy
 #
 # Proxy server to use for APT. Be careful when you set because of a bug which
 # causes this proxy to be used for all programs and not just apt as one might
-# expect. The default scripts use a workaround to still allow the apt proxy preseeding.
+# expect. The default scripts use a workaround to still allow the apt proxy
+# preseeding.
 preseed__debian_mirror_proxy: ''
 
 

docs/defaults-detailed.rst

@@ -9,7 +9,7 @@ them.
    :local:
    :depth: 1
 
-.. _preseed__configs:
+.. _preseed__section_detailed_configs:
 
 preseed__configs
 ----------------
@@ -19,7 +19,7 @@ clients.
 
 To make custom changes easier, preseed configuration file as well as the
 post-install script have default stored in the templates themselves, a subset
-of the available default variables is exposed in the ``defaults/main.yml``
+of the available default variables is exposed in the :file:`defaults/main.yml`
 file, however more esoteric variables were left out to keep the list of
 variables short.
 
@@ -32,7 +32,7 @@ Some more important keys:
 
 ``name``
   Name of the Preseed configuration, should be limited to alphanumeric
-  characters and a hypen (``-``) character. Will be used in the DNS do export
+  characters and a hyphen (``-``) character. Will be used in the DNS do export
   the configuration to the clients
 
 ``type``
@@ -43,8 +43,8 @@ Some more important keys:
   Specify the distribution release to configure. By default the current host
   release is used if none is specified
 
-Examples:
-~~~~~~~~~
+Examples
+~~~~~~~~
 
 Example Preseed configuration with custom mirror and list of additional
 packages to install::