docs: Allow passing additional params to `call_on_each_event`.

`call_on_each_event` now supports additional params other than
`event_type` and `narrow`; Ex: `all_public_streams` to fetch events
of all public streams.

Also add a bit of explanation of how this parameter works.

Fixes zulip/python-zulip-api#647

templates/zerver/api/real-time-events.md

@@ -13,8 +13,8 @@ The simplest way to use Zulip's real-time events API is by using
 `call_on_each_event` from our Python bindings.  You just need to write
 a Python function (in the examples below, the `lambda`s) and pass it
 into `call_on_each_event`; your function will be called whenever a new
-event matching the specific `event_type` and/or `narrow` parameters
-occurs in Zulip.
+event matching the specified parameters (`event_types`, `narrow`,
+etc.) occurs in Zulip.
 
 `call_on_each_event` takes care of all the potentially tricky details
 of long-polling, error handling, exponential backoff in retries, etc.

zerver/openapi/zulip.yaml

@@ -6485,15 +6485,7 @@ paths:
             default: false
           example: true
         - $ref: "#/components/parameters/Event_types"
-        - name: all_public_streams
-          in: query
-          description: |
-            Set to `True` if you would like to receive events that occur within all
-            public streams.
-          schema:
-            type: boolean
-            default: false
-          example: true
+        - $ref: "#/components/parameters/AllPublicStreams"
         - $ref: "#/components/parameters/IncludeSubscribers"
         - name: client_capabilities
           in: query
@@ -9254,8 +9246,9 @@ paths:
       description: |
         (Ignored)
       parameters:
-        - $ref: "#/components/parameters/Narrow"
         - $ref: "#/components/parameters/Event_types"
+        - $ref: "#/components/parameters/Narrow"
+        - $ref: "#/components/parameters/AllPublicStreams"
       security:
         - basicAuth: []
       responses:
@@ -10957,6 +10950,17 @@ components:
             default: []
           example: [["stream", "Denmark"]]
       required: false
+    AllPublicStreams:
+      name: all_public_streams
+      in: query
+      description: |
+        Whether you would like to request message events from all public
+        streams.  Useful for workflow bots that you'd like to see all new messages
+        sent to public streams.  (You can also subscribe the user to private streams).
+      schema:
+        type: boolean
+        default: false
+      example: true
     UserGroupId:
       name: user_group_id
       in: path