Browse Source

docs: standardize package descriptions and add missing example in site-example (#1179)

Ruben Barkow 6 years ago
parent
commit
a92cfa3194

+ 7 - 6
docs/package/gluon-config-mode-contact-info.rst

@@ -1,16 +1,17 @@
 gluon-config-mode-contact-info
 ==============================
 
-This package allows the user to provide contact information within config mode to be
-distributed in the mesh. You can define whether the owner contact field is
-obligatory or not in your site.conf.
+This package allows the user to provide contact information within config mode
+to be distributed in the mesh. You can define whether the owner contact field is
+obligatory or not in your ``site.conf``.
 
 site.conf
 ---------
 
-config_mode.owner.obligatory \: optional (defaults to false)
-  If ``obligatory`` is set to ``true``, the contact info field must be supplied
-  and may not be left empty.
+config_mode.owner.obligatory \: optional
+    - ``true`` the contact info field must be supplied and may not be left empty.
+    - ``false`` the contact info field may be left empty.
+    - defaults to ``false``
 
 Example::
 

+ 9 - 1
docs/package/gluon-config-mode-geo-location.rst

@@ -3,7 +3,7 @@ gluon-config-mode-geo-location
 
 This package enables the user to set latitude, longitude and altitude of their
 node within config mode. As the usage of the altitude is not well defined the
-corresponding field can be disabled.
+corresponding field can be disabled in your ``site.conf``.
 
 site.conf
 ---------
@@ -12,3 +12,11 @@ config_mode.geo_location.show_altitude : optional
     - ``true`` enables the altitude field
     - ``false`` disables the altitude field if altitude has not yet been set
     - defaults to ``true``
+
+Example::
+
+  config_mode = {
+    geo_location = {
+      show_altitude = true,
+    }
+  }

+ 6 - 3
docs/package/gluon-ebtables-source-filter.rst

@@ -6,8 +6,8 @@ ruleset to prevent unreasonable traffic entering the network via the nodes.
 Unreasonable means traffic entering the mesh via a node which source IP does
 not belong to the configured IP space.
 
-One may first check if there is a certain proportion of unreasonable traffic,
-before adding this package to the firmware image. Additional one should not
+You may first check if there is a certain proportion of unreasonable traffic,
+before adding this package to the firmware image. Furthermore, you should not
 use this package if some kind of gateway or upstream network is provided by
 a device connected to the client port.
 
@@ -27,4 +27,7 @@ Example::
 
   prefix4 = '198.51.100.0/21',
   prefix6 = '2001:db8:8::/64',
-  extra_prefixes6 = { '2001:db8:9::/64', '2001:db8:100::/60' },
+  extra_prefixes6 = {
+    '2001:db8:9::/64',
+    '2001:db8:100::/60',
+  },

+ 10 - 8
docs/package/gluon-web-admin.rst

@@ -9,15 +9,17 @@ password length must be.
 site.conf
 ---------
 
-config_mode.remote_login.show_password_form \: optional (defaults to ``false``)
-  If ``show_password_form`` is set to ``true``, the password section in
-  config mode is shown.
+config_mode.remote_login.show_password_form \: optional
+  - ``true`` the password section in config mode is shown
+  - ``false`` the password section in config mode is hidden
+  - defaults to ``false``
+  
+config_mode.remote_login.min_password_length \: optional
+  - sets the minimum allowed password length. Set this to ``1`` to disable the
+    length check.
+  - defaults to ``12``
 
-config_mode.remote_login.min_password_length \: optional (defaults to ``12``)
-  This sets the minimum allowed password length. Set this to ``1`` to
-  disable the length check.
-
-If you want to enable the password login you can use this example::
+Example::
 
   config_mode = {
     remote_login = {

+ 26 - 21
docs/site-example/site.conf

@@ -15,8 +15,8 @@
   -- Shorthand of the community.
   site_code = 'ffxx',
 
-  -- 32 bytes of random data, encoded in hexacimal
-  -- Must be the same of all nodes in one mesh domain
+  -- 32 bytes of random data, encoded in hexadecimal
+  -- Must be the same for all nodes in one mesh domain
   -- Can be generated using: echo $(hexdump -v -n 32 -e '1/1 "%02x"' </dev/urandom)
   site_seed = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
 
@@ -53,14 +53,14 @@
     -- ESSID used for client network.
     ap = {
       ssid = 'alpha-centauri.freifunk.net',
-      -- disabled = true, (optional)
+      -- disabled = true, -- (optional)
     },
 
     mesh = {
       -- Adjust these values!
       id = 'ueH3uXjdp', -- usually you don't want users to connect to this mesh-SSID, so use a cryptic id that no one will accidentally mistake for the client WiFi
       mcast_rate = 12000,
-      -- disabled = true, (optional)
+      -- disabled = true, -- (optional)
     },
   },
 
@@ -133,15 +133,15 @@
 
           -- Optional: nested peer groups
           -- groups = {
-          --   backbone_sub = {
-          --     ...
-          --   },
-          --   ...
+            -- backbone_sub = {
+              -- ...
+            -- },
+          -- ...
           -- },
         },
         -- Optional: additional peer groups, possibly with other limits
         -- backbone2 = {
-        --   ...
+          -- ...
         -- },
       },
     },
@@ -178,9 +178,9 @@
 
         -- List of public keys of maintainers.
         pubkeys = {
-                'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', -- Alice
-                'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', -- Bob
-                'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', -- Mary
+          'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', -- Alice
+          'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', -- Bob
+          'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', -- Mary
         },
       },
     },
@@ -188,18 +188,18 @@
 
   -- Node roles
   -- roles = {
-  --   default = 'node',
-  --   list = {
-  --     'node',
-  --     'test',
-  --     'backbone',
-  --     'service',
-  --   },
+    -- default = 'node',
+    -- list = {
+      -- 'node',
+      -- 'test',
+      -- 'backbone',
+      -- 'service',
+    -- },
   -- },
 
   -- Skip setup mode (config mode) on first boot
   -- setup_mode = {
-  --  skip = true,
+    -- skip = true,
   -- },
 
   -- config_mode = {
@@ -209,7 +209,12 @@
     -- },
     -- define if the contact field is obligatory (optional)
     -- owner = {
-      -- obligatory = true
+      -- obligatory = true,
+    -- },
+    -- Show/hide the password login
+    -- remote_login = {
+      -- show_password_form = true,
+      -- min_password_length = 12,
     -- },
   -- },