Add documentation for new config options

[ac000]

These two commits adds documentation for the new 'backlog' and 'listen_threads' config options.

[github-actions]

✅ Deploy Preview will be available once build job completes!

Name	Link
😎 Deploy Preview	https://frontdoor-test-docs.nginx.com/previews/unit/167/

---

[ac000]

(Seems I never actually posted this initital range-diff)

• Address feedback
• Add a patch that says from when server_version became available

$ git range-diff --creation-factor=100 8316baa...5e1f47e 
1:  f598cf5 ! 1:  eb6a71f Add documentation for new 'backlog' config option
    @@ source/configuration.rst: Available listener options:
              defines SSL/TLS
              :ref:`settings <configuration-listeners-ssl>`.
      
    -+    * - **backlog** *(since 1.33.0)*
    ++    * - **backlog**
     +      - Integer;
    -+        controls the 'backlog' parameter to the listen(2) system-call.
    ++        controls the 'backlog' parameter to the *listen(2)* system-call.
     +        This essentially limits the number of pending connections waiting
     +        to be accepted.
     +
    -+        The default varies by system. On Linux, FreeBSD, OpenBSD and macOS
    -+        we default (-1) to the OS's default. E.g. on Linux since 5.4 this is
    -+        4096, on FreeBSD it's 128.
    ++        The default varies by system.
     +
    -+        On other systems we default to 511.
    ++        On Linux, FreeBSD, OpenBSD and macOS the default is **-1** which
    ++        means use the OS default. For example. on Linux since 5.4, this is
    ++        **4096** (previously **128**) and on FreeBSD it's **128**.
     +
    -+        NOTE: Whatever limit you set here will be limited by the OS's
    -+        system-wide sysctl, e.g. on Linux net.core.somaxconn and on BSD
    -+        kern.ipc.somaxconn
    ++        On other systems default is **511**.
    ++
    ++        NOTE: Whatever limit you set here will be limited by the OS
    ++        system-wide sysctl. For example. on Linux that is
    ++        **net.core.somaxconn** and on BSD it's **kern.ipc.somaxconn**
    ++
    ++        *(since 1.33.0)*
      
      Here, a local listener accepts requests at port 8300
      and passes them to the **blogs** app
2:  8316baa ! 2:  083fb82 Add documentation for new 'listen_threads' config option
    @@ source/configuration.rst: that stores instance-wide preferences.
          * - Option
            - Description
      
    -+    * - **listen_threads** *(since 1.33.0)*
    ++    * - **listen_threads**
     +      - Integer;
    -+        controls the number of router threads created for handling client
    -+        connections. Each thread encompases all the configured listeners.
    ++        controls the number of router threads created to handle client
    ++        connections. Each thread includes all the configured listeners.
     +
    -+        By default we create the same number of threads as there are
    -+        available CPUs to run on.
    ++        By default, we create as many threads as the number of CPUs that
    ++        are available to run on.
    ++
    ++  *(since 1.33.0)*
     +
          * - **http**
            - Object;
-:  ------- > 3:  5e1f47e Note from which version server_version is available

Fix a tabs vs spaces snafu

$ git range-diff 5e1f47e...939daea
1:  083fb82 ! 1:  da53c37 Add documentation for new 'listen_threads' config option
    @@ source/configuration.rst: that stores instance-wide preferences.
     +        By default, we create as many threads as the number of CPUs that
     +        are available to run on.
     +
    -+  *(since 1.33.0)*
    ++        *(since 1.33.0)*
     +
          * - **http**
            - Object;
2:  5e1f47e = 2:  939daea Note from which version server_version is available

[ac000]

Add a missing 'the'

$ git range-diff 939daea...288b0b8
1:  da53c37 ! 1:  2a144c5 Add documentation for new 'listen_threads' config option
    @@ Commit message
         Signed-off-by: Andrew Clayton <[email protected]>
     
      ## source/configuration.rst ##
    +@@ source/configuration.rst: Available listener options:
    +         means use the OS default. For example. on Linux since 5.4, this is
    +         **4096** (previously **128**) and on FreeBSD it's **128**.
    + 
    +-        On other systems default is **511**.
    ++        On other systems the default is **511**.
    + 
    +         NOTE: Whatever limit you set here will be limited by the OS
    +         system-wide sysctl. For example. on Linux that is
     @@ source/configuration.rst: that stores instance-wide preferences.
          * - Option
            - Description
2:  939daea = 2:  288b0b8 Note from which version server_version is available

[Jcahilltorre]

Approved with some nits

[ac000]

• Add a commit documenting the new Python 'factory' option
• Add a commit clarifying the stdout/stderr options

$ git range-diff 288b0b8...756cf58
-:  ------- > 1:  5bb4909 Add documentation for new 'factory' Python config option
1:  288b0b8 = 2:  7efa1db Note from which version server_version is available
-:  ------- > 3:  756cf58 Clarify the stdout/stderr config options

[ac000]

When referencing another config option that should be bold not italic...

$ git range-diff 756cf58...ae637de
1:  5bb4909 ! 1:  28b26f3 Add documentation for new 'factory' Python config option
    @@ source/configuration.rst: you have:
      
     +    * - **factory*
     +      - Boolean:
    -+        when enabled, Unit treats *callable* as a factory.
    ++        when enabled, Unit treats **callable** as a factory.
     +
     +        The default is **false**.
     +
2:  7efa1db = 2:  8bb0539 Note from which version server_version is available
3:  756cf58 = 3:  ae637de Clarify the stdout/stderr config options

[ac000]

Fix boldening of 'factory'

$ git range-diff ae637de...e6d116b
1:  28b26f3 ! 1:  c41a3c4 Add documentation for new 'factory' Python config option
    @@ source/configuration.rst: you have:
      
              The default is **application**.
      
    -+    * - **factory*
    ++    * - **factory**
     +      - Boolean:
     +        when enabled, Unit treats **callable** as a factory.
     +
2:  8bb0539 = 2:  327a297 Note from which version server_version is available
3:  ae637de = 3:  e6d116b Clarify the stdout/stderr config options

[Jcahilltorre]

can this PR merged to release-1.33 now?

[ac000]

Yes

[Jcahilltorre]

The configuration file has moved in the release-1.33 branch. I don't see a way to reconcile the branches. I have transferred the updates in this PR to the new index.rst file that substitutes the configuration.rst file in this PR:

d91b4fe

Closing this PR as the content is now in the release branch.