Merge pull request #2349 from freifunk-gluon/doc-indent

docs: consistent indentation + minor fixes
freifunk-gluon · Dec 30, 2021 · a250177 · a250177
2 parents 4019293 + 543039d
commit a250177
Show file tree

Hide file tree

Showing 21 changed files with 789 additions and 777 deletions.
diff --git a/.editorconfig b/.editorconfig
@@ -25,7 +25,7 @@ indent_size = 4
 
 [*.rst]
 indent_style = space
-indent_size = 3
+indent_size = 2
 
 [*.yml]
 indent_style = space

diff --git a/docs/dev/basics.rst b/docs/dev/basics.rst
@@ -32,7 +32,7 @@ rerun
 
 ::
 
-	make update
+  make update
 
 `make update` also applies the patches that can be found in the directories found in
 `patches`; the resulting branch will be called `patched`, while the commit specified in `modules`
@@ -44,7 +44,7 @@ using
 
 ::
 
-	make update-patches
+  make update-patches
 
 If applying a patch fails because you have changed the base commit, the repository will be reset to the old `patched` branch
 and you can try rebasing it onto the new `base` branch yourself and after that call `make update-patches` to fix the problem.
@@ -54,7 +54,7 @@ commits, making `git reflog` the only way to recover them!
 
 ::
 
-	make refresh-patches
+  make refresh-patches
 
 In order to refresh patches when updating feeds or the OpenWrt base, `make refresh-patches` applies and updates all of their patches without installing feed packages to the OpenWrt buildsystem.
 

diff --git a/docs/dev/debugging.rst b/docs/dev/debugging.rst
@@ -32,12 +32,12 @@ The tooling is contained in the kernel source tree in the file
 `decode_stacktrace.sh <https://github.com/torvalds/linux/blob/master/scripts/decode_stacktrace.sh>`__.
 This file and the needed source tree are available in the directory: ::
 
-    openwrt/build_dir/target-<architecture>/linux-<architecture>/linux-<version>/
+  openwrt/build_dir/target-<architecture>/linux-<architecture>/linux-<version>/
 
 .. note::
-   Make sure to use a kernel tree that matches the version and patches
-   that was used to build the kernel.
-   If in doubt just re-build the images for the target.
+  Make sure to use a kernel tree that matches the version and patches
+  that was used to build the kernel.
+  If in doubt just re-build the images for the target.
 
 Some more information on how to use this tool can be found at
 `LWN <https://lwn.net/Articles/592724/>`__.
@@ -48,4 +48,4 @@ Obtaining Stacktraces
 On many targets stacktraces can be read from the following
 location after reboot: ::
 
-    /sys/kernel/debug/crashlog
+  /sys/kernel/debug/crashlog
diff --git a/docs/dev/packages.rst b/docs/dev/packages.rst
@@ -9,13 +9,16 @@ Development workflow
 When you are developing packages, it often happens that you iteratively want to deploy
 and verify the state your development. There are two ways to verify your changes:
 
-1) One way is to rebuild the complete firmware, flash it, configure it and verify your
-   development then. This usually takes at least a few minutes to get your changes
-   working so you can test them. Especially if you iterate a lot, this becomes tedious.
-2) Another way is to rebuild only the package you are currently working on and
-   to deploy this package to your test system. Here not even a reboot is required.
-   This makes iterating relatively fast. Your test system could be real hardware or
-   even a qemu in most cases.
+1)
+  One way is to rebuild the complete firmware, flash it, configure it and verify your
+  development then. This usually takes at least a few minutes to get your changes
+  working so you can test them. Especially if you iterate a lot, this becomes tedious.
+
+2)
+  Another way is to rebuild only the package you are currently working on and
+  to deploy this package to your test system. Here not even a reboot is required.
+  This makes iterating relatively fast. Your test system could be real hardware or
+  even a qemu in most cases.
 
 Gluon provides scripts to enhance workflow 2). Here is an example illustrating
 the workflow using these scripts:

diff --git a/docs/features/autoupdater.rst b/docs/features/autoupdater.rst
@@ -99,16 +99,16 @@ These commands can be used on a node:
 
 ::
 
-   # Update with some probability
-   autoupdater
+  # Update with some probability
+  autoupdater
 
 ::
 
-   # Force update check, even when the updater is disabled
-   autoupdater -f
+  # Force update check, even when the updater is disabled
+  autoupdater -f
 
 ::
 
-   # If fallback is true the updater will perform an update only if the timespan
-   # PRIORITY days (as defined in the manifest) and another 24h have passed
-   autoupdater --fallback
+  # If fallback is true the updater will perform an update only if the timespan
+  # PRIORITY days (as defined in the manifest) and another 24h have passed
+  autoupdater --fallback
diff --git a/docs/features/multidomain.rst b/docs/features/multidomain.rst
@@ -21,18 +21,18 @@ Overview
 Multidomain support allows to build a single firmware with multiple,
 switchable domain configurations. The nomenclature is as follows:
 
--  ``site``: an aggregate over multiple domains
--  ``domain``: mesh network with connectivity parameters that prevent
-   accidental bridging with other domains
--  ``domain code``: unique domain identifier
--  ``domain name``: pretty name for a domain code
+- ``site``: an aggregate over multiple domains
+- ``domain``: mesh network with connectivity parameters that prevent
+  accidental bridging with other domains
+- ``domain code``: unique domain identifier
+- ``domain name``: pretty name for a domain code
 
 By default Gluon builds firmware with a single domain embedded into
 ``site.conf``. To use multiple domains, enable it in ``site.mk``:
 
 ::
 
-    GLUON_MULTIDOMAIN=1
+  GLUON_MULTIDOMAIN=1
 
 In the site repository, create the ``domains/`` directory, which will
 hold your domain configurations. Each domain configuration file is named
@@ -41,26 +41,26 @@ supported.
 
 ::
 
-    site/
-    |-- site.conf
-    |-- site.mk
-    |-- i18n/
-    |-- domains/
-      |-- alpha_centauri.conf
-      |-- beta_centauri.conf
-      |-- gamma_centauri.conf
+  site/
+  |-- site.conf
+  |-- site.mk
+  |-- i18n/
+  |-- domains/
+    |-- alpha_centauri.conf
+    |-- beta_centauri.conf
+    |-- gamma_centauri.conf
 
 The domain configuration ``alpha_centauri.conf`` could look like this.
 
 ::
 
-    {
-      domain_names = {
-        alpha_centauri = 'Alpha Centauri'
-      },
+  {
+    domain_names = {
+      alpha_centauri = 'Alpha Centauri'
+    },
 
-      -- more domain specific config follows below
-    }
+    -- more domain specific config follows below
+  }
 
 In this example “Alpha Centauri” is the user-visible ``domain_name`` for the
 domain_code ``alpha_centauri``. Also note that the domain code
@@ -93,12 +93,12 @@ Via commandline
 
 ::
 
-    gluon-switch-domain 'newdomaincode'
+  gluon-switch-domain 'newdomaincode'
 
 When the node is not in config mode, ``gluon-switch-domain`` will automatically
 reboot the node by default. This can be suppressed by passing ``--no-reboot``::
 
-    gluon-switch-domain --no-reboot 'newdomaincode'
+  gluon-switch-domain --no-reboot 'newdomaincode'
 
 Switching the domain without reboot is currently **experimental**.
 
@@ -123,115 +123,115 @@ site or domain context.
 site.conf only variables
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
--  Used in as initial default values, when the firmware was just flashed
-   and/or the config mode is skipped, so they do not make sense in a
-   domain specific way:
-
-   -  authorized_keys
-   -  default_domain
-   -  poe_passthrough
-   -  mesh_on_wan
-   -  mesh_on_lan
-   -  single_as_lan
-   -  setup_mode.skip
-   -  autoupdater.branch
-   -  mesh_vpn.enabled
-   -  mesh_vpn.pubkey_privacy
-   -  mesh_vpn.bandwidth_limit
-   -  mesh_vpn.bandwidth_limit.enabled
-   -  mesh_vpn.bandwidth_limit.ingress
-   -  mesh_vpn.bandwidth_limit.egress
-
--  Variables that influence the appearance of the config mode,
-   domain-independent because they are relevant before a domain was selected.
-
-   -  config_mode.geo_location.show_altitude
-   -  config_mode.hostname.optional
-   -  config_mode.remote_login
-   -  config_mode.remote_login.show_password_form
-   -  config_mode.remote_login.min_password_length
-   -  hostname_prefix
-   -  mesh_vpn.fastd.configurable
-   -  roles.default
-   -  roles.list
-
--  Specific to a firmware build itself:
-
-   -  site_code
-   -  site_name
-   -  autoupdater.branches.*.name
-   -  autoupdater.branches.*.good_signatures
-   -  autoupdater.branches.*.pubkeys
-
--  We simply do not see any reason, why these variables could be helpful
-   in a domain specific way:
-
-   -  mesh_vpn.fastd.syslog_level
-   -  timezone
-   -  regdom
+- Used in as initial default values, when the firmware was just flashed
+  and/or the config mode is skipped, so they do not make sense in a
+  domain specific way:
+
+  - authorized_keys
+  - default_domain
+  - poe_passthrough
+  - mesh_on_wan
+  - mesh_on_lan
+  - single_as_lan
+  - setup_mode.skip
+  - autoupdater.branch
+  - mesh_vpn.enabled
+  - mesh_vpn.pubkey_privacy
+  - mesh_vpn.bandwidth_limit
+  - mesh_vpn.bandwidth_limit.enabled
+  - mesh_vpn.bandwidth_limit.ingress
+  - mesh_vpn.bandwidth_limit.egress
+
+- Variables that influence the appearance of the config mode,
+  domain-independent because they are relevant before a domain was selected.
+
+  - config_mode.geo_location.show_altitude
+  - config_mode.hostname.optional
+  - config_mode.remote_login
+  - config_mode.remote_login.show_password_form
+  - config_mode.remote_login.min_password_length
+  - hostname_prefix
+  - mesh_vpn.fastd.configurable
+  - roles.default
+  - roles.list
+
+- Specific to a firmware build itself:
+
+  - site_code
+  - site_name
+  - autoupdater.branches.*.name
+  - autoupdater.branches.*.good_signatures
+  - autoupdater.branches.*.pubkeys
+
+- We simply do not see any reason, why these variables could be helpful
+  in a domain specific way:
+
+  - mesh_vpn.fastd.syslog_level
+  - timezone
+  - regdom
 
 domain.conf only variables
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
--  Obviously:
+- Obviously:
 
-   -  domain_names
+  - domain_names
 
-      -  a table of domain codes to domain names
-         ``domain_names = { foo = 'Foo Domain', bar = 'Bar Domain', baz = 'Baz Domain' }``
+    - a table of domain codes to domain names
+      ``domain_names = { foo = 'Foo Domain', bar = 'Bar Domain', baz = 'Baz Domain' }``
 
-   -  hide_domain
+  - hide_domain
 
-      -  prevents a domain name(s) from appearing in config mode, either
-         boolean or array of domain codes
+    - prevents a domain name(s) from appearing in config mode, either
+      boolean or array of domain codes
 
-         -  ``true``, ``false``
-         -  ``{ 'foo', 'bar' }``
+      - ``true``, ``false``
+      - ``{ 'foo', 'bar' }``
 
--  Because each domain is considered as an own layer 2 network, these
-   values should be different in each domain:
+- Because each domain is considered a separate layer 2 network, these
+  values should be different in each domain:
 
-   -  next_node.ip4
-   -  next_node.ip6
-   -  next_node.name
-   -  prefix6
-   -  prefix4
-   -  extra_prefixes6
+  - next_node.ip4
+  - next_node.ip6
+  - next_node.name
+  - prefix6
+  - prefix4
+  - extra_prefixes6
 
--  To prevent accidental bridging of different domains, all meshing
-   technologies should be separated:
+- To prevent accidental bridging of different domains, all meshing
+  technologies should be separated:
 
-   -  domain_seed (wired mesh)
+  - domain_seed (wired mesh)
 
-      -  must be a random value used to derive the vxlan id for wired meshing
+    - must be a random value used to derive the vxlan id for wired meshing
 
-   -  wifi*.mesh.id
-   -  mesh_vpn.fastd.groups.*.peers.remotes
-   -  mesh_vpn.fastd.groups.*.peers.key
-   -  mesh_vpn.tunneldigger.brokers
+  - wifi*.mesh.id
+  - mesh_vpn.fastd.groups.*.peers.remotes
+  - mesh_vpn.fastd.groups.*.peers.key
+  - mesh_vpn.tunneldigger.brokers
 
--  Clients consider WiFi networks sharing the same ESSID as if they were
-   the same L2 network and try to reconfirm and reuse previous
-   addressing. If multiple neighbouring domains shared the same ESSID,
-   the roaming experience of clients would degrade.
+- Clients consider WiFi networks sharing the same ESSID as if they were
+  the same L2 network and try to reconfirm and reuse previous
+  addressing. If multiple neighbouring domains shared the same ESSID,
+  the roaming experience of clients would degrade.
 
-   -  wifi*.ap.ssid
+  - wifi*.ap.ssid
 
--  Some values should be only set in legacy domains and not in new domains.
+- Some values should be only set in legacy domains and not in new domains.
 
-   -  mesh.vxlan
+  - mesh.vxlan
 
-      -  By default, this value is `true`. It should be only set to `false`
-         for one legacy domain, since vxlan prevents accidental wired
-         merges of domains. For old domains this value is still available
-         to keep compatibility between all nodes in one domain.
+    - By default, this value is `true`. It should be only set to `false`
+      for one legacy domain, since vxlan prevents accidental wired
+      merges of domains. For old domains this value is still available
+      to keep compatibility between all nodes in one domain.
 
-   -  next_node.mac
+  - next_node.mac
 
-      -  For new domains, the default value should be used, since there is
-         no need for a special mac (or domain specific mac). For old domains
-         this value is still available to keep compatibility between all
-         nodes in one domain.
+    - For new domains, the default value should be used, since there is
+      no need for a special mac (or domain specific mac). For old domains
+      this value is still available to keep compatibility between all
+      nodes in one domain.
 
 Example config
 --------------