DOC-8425 -- Revise Channels Documentation (#490)

https://issues.couchbase.com/browse/DOC-8425

Author: ibsoln

modules/ROOT/assets/attachments/sg.yaml

@@ -277,7 +277,7 @@ properties:
                   enable_star_channel:
                     type: boolean
                     description: |+
-                      Enable the star (*) channel.
+                      Enable the all documents (*) channel -- sometimes referred to as the 'star' channel.
                     default: 'true'
                   max_length:
                     type: integer
@@ -612,9 +612,11 @@ properties:
                 properties:
                   admin_channels:
                     type: array
-                    description: |
+                    description: |+
                       The list of channels this role is automatically granted access to when Sync Gateway starts.
-                      If "*" is specified then the role is granted access to the star channel which contains all documents.
+
+                      If you use the all channels wildcard ("*") the role is granted access to all channels and to all documents within all channels. This will be inherited by any user assigned this role.
+
                     items:
                       type: string
           send_www_authenticate_header:
@@ -806,7 +808,11 @@ properties:
                     description: The user's password.
                   admin_channels:
                     type: array
-                    description: The list of channels this user is automatically granted access to when Sync Gateway starts. If `"*"` is specified then the user is granted access to the [star channel](sync-gateway-channels.html#special-channels) which contains all documents.
+                    description: |+
+                      The list of channels this user is automatically granted access to when Sync Gateway starts.
+
+                      If you use the all channels wildcard ("*") the user is granted access to all channels and to all documents within all channels -- see: [all channels wildcard](channels.html#lbl-all-channels).
+
                     items:
                       type: string
                   admin_roles:
@@ -1301,6 +1307,11 @@ properties:
                         These details are used to authenticate credentials and approve access to data
 
                         Once provided and recorded, the username data is redacted and will not be displayed in either the configuration file or Admin REST API. A string of `****` will be displayed in its place.
+
+                        Replications initiated by this user will pull all documents in all channels the user has access grants for.
+                        If the all channels wildcard was used to grant access then the sync will pull *ALL* documents.
+                        Use a filter to avoid syncing excessive amounts of data to mobile devices.
+
   facebook:
     description: Configuration for Facebook Login authentication.
     type: object

modules/ROOT/assets/attachments/sync-gateway-admin.yaml

@@ -1478,7 +1478,7 @@ paths:
               admin_channels:
                 type: array
                 description: |
-                  The admin channels that this role has granted access to. Admin channels are the ones which were
+                  The admin channels that this role has granted access to. Admin channels are the ones which are
                   granted access to in the config file or via the Admin REST API.
                 items:
                   type: string
@@ -2507,7 +2507,7 @@ definitions:
     properties:
       channels:
         type: object
-        description: Key-value pairs with a channel name as the key and the sequence number that granted the user access to the channel as value. `!` is the public channel and every user has access to it.
+        description: Key-value pairs with a channel name as the key and the sequence number that granted the user access to the channel as value.Note that `!` is the public channel and every user has access to it.
       name:
         type: string
         description: The user's name.

modules/ROOT/pages/_partials/_page-index.adoc

@@ -252,6 +252,7 @@ endif::xref--pfx-sgw[]
 :supported-environments--xref: {sgw--xref}{supported-environments--page}[Supported Environments]
 :sync-function--page:  sync-function.adoc
 :sync-function--xref: {sgw--xref}{sync-function--page}[Sync Function]
+:sync-function--bmk-requireAcces: {sgw--xref}{sync-function--page}[Sync Function -- requireAccess()]
 :sync-inter-syncgateway-conflict-resolution--page: sync-inter-syncgateway-conflict-resolution.adoc
 :sync-inter-syncgateway-conflict-resolution--xref: {sgw--xref}{sync-inter-syncgateway-conflict-resolution--page}[Inter Sync Gateway Sync -  Conflict Resolution]
 :sync-inter-syncgateway-manage--page:  sync-inter-syncgateway-manage.adoc

modules/ROOT/pages/_partials/topic-group-access-control.adoc

@@ -0,0 +1,78 @@
+// BEGIN -- inclusion -- topic-group-access-control.adoc
+//  Purpose:
+//    Show the topic group, allowing easy cycle-through
+//    Do not show current page as a click-through though
+//  Container: /modules/ROOT/pages/_partials/
+
+// BEGIN -- get the current calling page's name
+:this-page: {page-relative-src-path}
+// END -- get the current calling page's name
+
+// Begin -- Define Local Attributes with Required Links and Titles for this topic group
+// Set titles for xrefs
+:title-1: Sync function
+:title-2: Read access
+:title-3: Write access
+// :title-4: Revisions
+// :title-5: Tombstones
+
+
+// Set the pages for the xrefs to link to (we are using attributes from _page-index.adoc here)
+:topic-1: {sync-function--page}
+:topic-2: {read-access--page}
+:topic-3: {write-access-page}
+// :topic-4: {revisions--page}
+// :topic-5: {what-are-tombstones--page}
+// Set the xrefs up using attribute from _page-index.adoc and above attributes
+:topic-1--xref: {sgw--xref}{topic-1}[{title-1}]
+:topic-2--xref: {sgw--xref}{topic-2}[{title-2}]
+:topic-3--xref: {sgw--xref}{topic-3}[{title-3}]
+// :topic-4--xref: {sgw--xref}{topic-4}[{title-4}]
+// :topic-5--xref: {sgw--xref}{topic-5}[{title-5}]
+// End -- Local Attributes
+
+// Begin -- Remove the xref link from current calling page
+ifeval::["{this-page}"=="{topic-1}"]
+:topic-1--xref: pass:q,a[*{title-1}*]
+endif::[]
+
+ifeval::["{this-page}"=="{topic-2}"]
+:topic-2--xref: {title-2}
+endif::[]
+
+ifeval::["{this-page}"=="{topic-3}"]
+:topic-3--xref: {title-3}
+endif::[]
+
+// ifeval::["{this-page}"=="{topic-4}"]
+// :topic-4--xref: {title-4}
+// endif::[]
+
+// ifeval::["{this-page}"=="{topic-5}"]
+// :topic-5--xref: {title-5}
+// endif::[]
+// End -- Remove xref link from current page
+// Begin -- Output Block
+_Related {param-topic-group} topics_:  {topic-1--xref}  |  {topic-2--xref}  |  {topic-3--xref}  |  {topic-4--xref}  |  {topic-5--xref}
+// End -- Output Block
+
+// Begin -- Tidy-up
+:this-page!:
+:topic-1!:
+:topic-2!:
+:topic-3!:
+// :topic-4!:
+// :topic-5!:
+:title-1!:
+:title-2!:
+:title-3!:
+// :title-4!:
+// :title-5!:
+:topic-1--xref!:
+:topic-2--xref!:
+:topic-3--xref!:
+// :topic-4--xref!:
+// :topic-5--xref!:
+// End -- Tidy-up
+
+// END -- inclusion -- content-group-configuration.adoc

modules/ROOT/pages/_partials/topic-group-concepts.adoc

@@ -0,0 +1,80 @@
+// BEGIN -- inclusion -- topic-group-concepts.adoc
+//  Purpose:
+//    Show the topic group, allowing easy cycle-through
+//    Do not show current page as a click-through though
+//  Container: /modules/ROOT/pages/_partials/
+
+// BEGIN -- get the current calling page's name
+:this-page: {page-relative-src-path}
+// END -- get the current calling page's name
+
+// Begin -- Define Local Attributes with Required Links and Titles for this topic group
+// Set titles for xrefs
+:title-1: Users
+:title-2: Roles
+:title-3: Channels
+:title-4: Revisions
+:title-5: Tombstones
+
+
+// Set the pages for the xrefs to link to (we are using attributes from _page-index.adoc here)
+:topic-1: {users--page}
+:topic-2: {roles--page}
+:topic-3: {channels--page}
+:topic-4: {revisions--page}
+:topic-5: {what-are-tombstones--page}
+
+
+// Set the xrefs up using attribute from _page-index.adoc and above attributes
+:topic-1--xref: {sgw--xref}{topic-1}[{title-1}]
+:topic-2--xref: {sgw--xref}{topic-2}[{title-2}]
+:topic-3--xref: {sgw--xref}{topic-3}[{title-3}]
+:topic-4--xref: {sgw--xref}{topic-4}[{title-4}]
+:topic-5--xref: {sgw--xref}{topic-5}[{title-5}]
+// End -- Local Attributes
+
+// Begin -- Remove the xref link from current calling page
+ifeval::["{this-page}"=="{topic-1}"]
+:topic-1--xref: pass:q,a[*{title-1}*]
+endif::[]
+
+ifeval::["{this-page}"=="{topic-2}"]
+:topic-2--xref: {title-2}
+endif::[]
+
+ifeval::["{this-page}"=="{topic-3}"]
+:topic-3--xref: {title-3}
+endif::[]
+
+ifeval::["{this-page}"=="{topic-4}"]
+:topic-4--xref: {title-4}
+endif::[]
+
+ifeval::["{this-page}"=="{topic-5}"]
+:topic-5--xref: {title-5}
+endif::[]
+// End -- Remove xref link from current page
+// Begin -- Output Block
+_Related {param-topic-group} topics_:  {topic-1--xref}  |  {topic-2--xref}  |  {topic-3--xref}  |  {topic-4--xref}  |  {topic-5--xref}
+// End -- Output Block
+
+// Begin -- Tidy-up
+:this-page!:
+:topic-1!:
+:topic-2!:
+:topic-3!:
+:topic-4!:
+:topic-5!:
+:title-1!:
+:title-2!:
+:title-3!:
+:title-4!:
+:title-5!:
+:topic-1--xref!:
+:topic-2--xref!:
+:topic-3--xref!:
+:topic-4--xref!:
+:topic-5--xref!:
+// End -- Tidy-up
+
+// END -- inclusion -- content-group-configuration.adoc