Separate authentication and monitoring docs & reorganize admin tasks (#1028)

* Separate authentication and monitoring docs

* Move collections and preferences documentation

* Rename admin tasks to database tasks

Author: p-mongo

source/ruby-driver-tutorials.txt

@@ -16,13 +16,15 @@ operations available in the Ruby driver.
    :titlesonly:
 
    /tutorials/ruby-driver-create-client
+   /tutorials/ruby-driver-authentication
    /tutorials/ruby-driver-crud-operations
    /tutorials/ruby-driver-collection-tasks
    /tutorials/ruby-driver-projections
    /tutorials/ruby-driver-sessions
    /tutorials/ruby-driver-transactions
    /tutorials/ruby-driver-change-streams
-   /tutorials/ruby-driver-admin-tasks
+   /tutorials/ruby-driver-database-tasks
+   /tutorials/ruby-driver-monitoring
    /tutorials/ruby-driver-indexing
    /tutorials/ruby-driver-collations
    /tutorials/ruby-driver-aggregation

source/tutorials/ruby-driver-admin-tasks.txt renamed to source/tutorials/ruby-driver-authentication.txt

@@ -1,5 +1,5 @@
 ==============
-Administration
+Authentication
 ==============
 
 .. default-domain:: mongodb
@@ -10,90 +10,6 @@ Administration
    :depth: 1
    :class: singlecol
 
-Databases
----------
-
-The driver provides various helpers on database objects for executing
-commands, getting collection lists, and administrative tasks.
-
-List Collections
-````````````````
-
-To get a list of collections or collection names for a database, use
-``collections`` and ``collection_names``, respectively.
-
-.. code-block:: ruby
-
-  client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
-  database = client.database
-
-  database.collections # Returns an array of Collection objects.
-  database.collection_names # Returns an array of collection names as strings.
-
-To execute any command on the database, use the ``command`` method.
-
-.. code-block:: ruby
-
-  client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
-  database = client.database
-
-  result = database.command(:ismaster => 1)
-  result.first # Returns the BSON::Document returned from the server.
-
-Drop Database
-`````````````
-
-To drop a database, use the ``drop`` method.
-
-.. code-block:: ruby
-
-  client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
-  client.database.drop
-
-Collections
------------
-
-The driver provides some helpers for administrative tasks with
-collections.
-
-To create a collection with options (such as creating a capped collection),
-pass the options when getting the collection from the client, then call
-``create``.
-
-.. code-block:: ruby
-
-  client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
-  artists = client[:artists, :capped => true, :size => 1024]
-  artists.create
-  artists.capped? # Returns true.
-
-Drop Collection
-```````````````
-
-To drop a collection, call ``drop`` on the collection object.
-
-.. code-block:: ruby
-
-  client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
-  artists = client[:artists]
-  artists.drop
-
-Changing Read/Write Preferences
-```````````````````````````````
-
-To change the default read preference or write concern for specific operations,
-use the ``with`` method on the collection.
-
-.. code-block:: ruby
-
-  client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
-  artists = client[:artists]
-  artists.with(:read => { :mode => :primary_preferred }).find.to_a
-  artists.with(:write => { :w => :3 }).insert_one( { :name => 'Depeche Mode' } )
-
-Authentication
---------------
-
 MongoDB supports a variety of 
 :manual:`authentication mechanisms </core/authentication/>`.
 
@@ -258,119 +174,3 @@ authentication, see the :manual:`manual
                              auth_mech: :gssapi,
                              user: 'test',
                              password: '123' )
-
-Logger
-------
-
-You can either use the default global driver logger or set your own. To set your own:
-
-.. code-block:: ruby
-
-  Mongo::Logger.logger = other_logger
-
-See the `Ruby Logger documentation <http://ruby-doc.org/stdlib-2.2.0/libdoc/logger/rdoc/Logger.html>`_
-for more information on the default logger API and available levels. 
-
-Changing the Logger Level
-`````````````````````````
-
-To change the logger level:
-
-.. code-block:: ruby
-
-  Mongo::Logger.logger.level = Logger::WARN
-
-For more control, a logger can be passed to a client for per-client control over logging.
-
-.. code-block:: ruby
-
-  my_logger = Logger.new($stdout)
-  Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'test', :logger => my_logger )
-
-Truncation
-``````````
-
-The default logging truncates logs at 250 characters by default. To turn this off pass an
-option to the client instance.
-
-.. code-block:: ruby
-
-  Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'test', :truncate_logs => false )
-
-Monitoring
-----------
-
-All user-initiated commands that are sent to the server publish events that can be
-subscribed to for fine grained information. The monitoring API publishes a guaranteed
-start event for each command, then either a succeeded or failed event. A subscriber
-must implement 3 methods: ``started``, ``succeeded``, and ``failed``, each which takes
-a single parameter for the event. An example is the default logging subscriber included
-in the driver:
-
-.. code-block:: ruby
-
-  module Mongo
-    class Monitoring
-      class CommandLogSubscriber
-        include Loggable
-
-        attr_reader :options
-
-        LOG_STRING_LIMIT = 250
-
-        def initialize(options = {})
-          @options = options
-        end
-
-        def started(event)
-          log_debug("#{prefix(event)} | STARTED | #{format_command(event.command)}")
-        end
-
-        def succeeded(event)
-          log_debug("#{prefix(event)} | SUCCEEDED | #{event.duration}s")
-        end
-
-        def failed(event)
-          log_debug("#{prefix(event)} | FAILED | #{event.message} | #{event.duration}s")
-        end
-
-        private
-
-        def format_command(args)
-          begin
-            truncating? ? truncate(args) : args.inspect
-          rescue Exception
-            '<Unable to inspect arguments>'
-          end
-        end
-
-        def prefix(event)
-          "#{event.address.to_s} | #{event.database_name}.#{event.command_name}"
-        end
-
-        def truncate(command)
-          ((s = command.inspect).length > LOG_STRING_LIMIT) ? "#{s[0..LOG_STRING_LIMIT]}..." : s
-        end
-
-        def truncating?
-          @truncating ||= (options[:truncate_logs] != false)
-        end
-      end
-    end
-  end
-
-To register a custom subscriber, you can do so globally for
-all clients or on a per-client basis:
-
-.. code-block:: ruby
-
-  Mongo::Monitoring::Global.subscribe(Mongo::Monitoring::COMMAND, my_subscriber)
-
-  client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'test' )
-  client.subscribe( Mongo::Monitoring::COMMAND, my_subscriber )
-
-To turn off monitoring, set the client monitoring option to ``false``:
-
-.. code-block:: ruby
-
-  client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'test', :monitoring => false )

source/tutorials/ruby-driver-collection-tasks.txt

@@ -17,8 +17,8 @@ document in that collection.
 You can also explicitly create a collection with various options,
 such as setting the maximum size or the documentation validation rules.
 
-Capped Collection
-`````````````````
+Capped Collections
+``````````````````
 
 Capped collections have maximum size or document counts that prevent
 them from growing beyond maximum thresholds. All capped collections must
@@ -32,7 +32,9 @@ the ``capped: true`` option along with a ``size`` in bytes.
 .. code-block:: ruby
 
   client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
-  client[:artists, capped: true, size: 10000].create
+  collection = client[:artists, capped: true, size: 10000]
+  collection.create
+  collection.capped? # => true
 
 Convert an Existing Collection to Capped
 ````````````````````````````````````````
@@ -42,9 +44,9 @@ the ``convertToCapped`` command.
 
 .. code-block:: ruby
 
-  client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'test')
+  client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
   db = client.database
-  db.command({ 'convertToCapped' => 'contacts', 'size' => 8192 })
+  db.command({ 'convertToCapped' => 'artists', 'size' => 10000 })
 
 
 Document Validation
@@ -102,52 +104,27 @@ documents must contain an ``age`` field which is a number.
                  }
              })
 
+Listing Collections
+```````````````````
 
-Change Streams
-```````````````
-
-As of version 3.6 of the MongoDB server, a new ```$changeStream`` pipeline stage is supported in the aggregation framework.
-Specifying this stage first in an aggregation pipeline allows users to request that notifications are sent for all
-changes to a particular collection. The helper method available for change streams on a collection object is preferred
-to running a raw aggregation with a $changeStream stage, for the purpose of supporting resumability.
-
-The change stream will attempt to resume one time upon a network error or a server error indicating that a failover is
-taking place.
-
-To start receiving change notifications, use the method ``#watch`` on a collection:
-
-.. code-block:: ruby
-
-  client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'test')
-  stream = client[:test].watch
-
-Each document can be retrieved and processed by your application as in the following code example:
+Use ``collections`` or ``collection_names`` methods on a database
+objects to list collections:
 
 .. code-block:: ruby
 
-  enum = stream.to_enum
-  begin
-    while true
-      change = enum.next
-      # do something
-      sleep(1)
-    end
-  rescue => e
-    # we know for sure it's unrecoverable
-    log_error(e)
-  end
-
-The change documents will expose a resume token at the key '_id'. This token can be used to specify a logical starting
-point for a new a ChangeStream:
+  client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
+  database = client.database
 
-.. code-block:: ruby
+  database.collections      # Returns an array of Collection objects.
+  database.collection_names # Returns an array of collection names as strings.
 
-  stream = client[:test].watch([], resume_token: token)
+Dropping Collections
+````````````````````
 
-A subset of aggregation pipeline stages are available to a change stream and can be passed into the ``#watch`` method:
+To drop a collection, call ``drop`` on the collection object.
 
 .. code-block:: ruby
 
-  stream = client[:test].watch([ { '$match' => { 'operationType' => 'update' } }])
-
-
+  client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music')
+  artists = client[:artists]
+  artists.drop

source/tutorials/ruby-driver-create-client.txt

@@ -658,3 +658,41 @@ be automatically retried:
 - ``collection#find_one_and_replace``
 - ``collection#find_one_and_delete``
 - ``collection#bulk_write`` (for all single statement ops, i.e. not for ``update_many`` or ``delete_many``)
+
+Logging
+-------
+
+You can either use the default global driver logger or set your own. To set your own:
+
+.. code-block:: ruby
+
+  Mongo::Logger.logger = other_logger
+
+See the `Ruby Logger documentation <http://ruby-doc.org/stdlib-2.2.0/libdoc/logger/rdoc/Logger.html>`_
+for more information on the default logger API and available levels. 
+
+Changing the Logger Level
+`````````````````````````
+
+To change the logger level:
+
+.. code-block:: ruby
+
+  Mongo::Logger.logger.level = Logger::WARN
+
+For more control, a logger can be passed to a client for per-client control over logging.
+
+.. code-block:: ruby
+
+  my_logger = Logger.new($stdout)
+  Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'test', :logger => my_logger )
+
+Truncation
+``````````
+
+The default logging truncates logs at 250 characters by default. To turn this off pass an
+option to the client instance.
+
+.. code-block:: ruby
+
+  Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'test', :truncate_logs => false )