Various documentation updates

CONTRIBUTING.md

@@ -60,18 +60,10 @@ repository:
    repository.
  * Install [giza](https://pypi.python.org/pypi/giza/), as noted in the tools
    README.
- * Comment out the following `assets` entry in `config/build_conf.yaml`:
-   ```
-   - branch: master
-      path: build/php-library # this is where we'll put the source docs (from the driver repo)
-      repository: https://github.com/mongodb/mongo-php-library.git
-   ```
-
- * Create a symlink so that `build/php-library` points to your working copy of
-   the [mongodb/mongo-php-library](https://github.com/mongodb/mongo-php-library)
-   repository.
- * Build the documentation with `giza make html`. You can suppress informational
-   log messages via the `--level warning` option.
+ * Sync your working copy of the documentation to the `source/` directory with
+   `rsync -a --delete /path/to/mongo-php-library/docs/ source/`.
+ * Build the documentation with `giza make publish`. You can suppress
+   informational log messages with the `--level warning` option.
  * Generated documentation may be found in the `build/master/html` directory.
 
 ## Releasing

docs/includes/apiargs-MongoDBClient-method-construct-driverOptions.yaml

@@ -17,4 +17,99 @@ description: |
 interface: phpmethod
 operation: ~
 optional: true
+---
+arg_name: option
+name: allow_invalid_hostname
+type: boolean
+description: |
+  Disables hostname validation if ``true``. Defaults to ``false``.
+
+  Allowing invalid hostnames may expose the driver to a `man-in-the-middle
+  attack <https://en.wikipedia.org/wiki/Man-in-the-middle_attack>`_.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
+name: ca_dir
+type: string
+description: |
+  Path to a correctly hashed certificate directory. The system certificate store
+  will be used by default.
+
+  Falls back to the deprecated ``capath`` SSL context option if not specified.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
+name: ca_file
+type: string
+description: |
+  Path to a certificate authority file. The system certificate store will be
+  used by default.
+
+  Falls back to the deprecated ``cafile`` SSL context option if not specified.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
+name: crl_file
+type: string
+description: |
+  Path to a certificate revocation list file.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
+name: pem_file
+type: string
+description: |
+  Path to a PEM encoded certificate to use for client authentication.
+
+  Falls back to the deprecated ``local_cert`` SSL context option if not
+  specified.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
+name: pem_pwd
+type: string
+description: |
+  Passphrase for the PEM encoded certificate (if applicable).
+
+  Falls back to the deprecated ``passphrase`` SSL context option if not
+  specified.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
+name: weak_cert_validation
+type: boolean
+description: |
+  Disables certificate validation ``true``. Defaults to ``false``.
+
+  Falls back to the deprecated ``allow_self_signed`` SSL context option if not
+  specified.
+interface: phpmethod
+operation: ~
+optional: true
+---
+arg_name: option
+name: context
+type: resource
+description: |
+  :php:`SSL context options <manual/en/context.ssl.php>` to be used as fallbacks
+  for other driver options (as specified). Note that the driver does not consult
+  the default stream context.
+
+  This option is supported for backwards compatibility, but should be considered
+  deprecated.
+interface: phpmethod
+operation: ~
+optional: true
 ...

docs/includes/apiargs-MongoDBClient-method-construct-param.yaml

@@ -3,10 +3,18 @@ name: $uri
 type: string
 description: |
   The URI of the standalone, replica set, or sharded cluster to which to
-  connect. Refer to the :manual:`MongoDB connection string reference
-  </reference/connection-string>` for formatting.
+  connect. Refer to :manual:`Connection String URI Format
+  </reference/connection-string>` in the MongoDB manual for more information.
 
   Defaults to ``"mongodb://127.0.0.1:27017"`` if unspecified.
+
+  Any special characters in the URI components need to be encoded according to
+  `RFC 3986 <http://www.faqs.org/rfcs/rfc3986.html>`_. This is particularly
+  relevant to the username and password, which can often include special
+  characters such as ``@``, ``:``, or ``%``. When connecting via a Unix domain
+  socket, the socket path may contain special characters such as slashes and
+  must be encoded. The :php:`rawurlencode() <rawurlencode>` function may be used
+  to encode constituent parts of the URI.
 interface: phpmethod
 operation: ~
 optional: true
@@ -17,7 +25,8 @@ type: array
 description: |
   Specifies additional URI options, such as authentication credentials or query
   string parameters. The options specified in ``$uriOptions`` take precedence
-  over any analogous options present in the ``$uri`` string.
+  over any analogous options present in the ``$uri`` string and do not need to
+  be encoded according to `RFC 3986 <http://www.faqs.org/rfcs/rfc3986.html>`_.
 
   Refer to the :php:`MongoDB\\Driver\\Manager::__construct()
   <mongodb-driver-manager.construct>` extension reference and :manual:`MongoDB

docs/includes/extracts-error.yaml

@@ -0,0 +1,33 @@
+ref: error-driver-invalidargumentexception
+content: |
+  :php:`MongoDB\\Driver\\Exception\\InvalidArgumentException
+  <mongodb-driver-exception-invalidargumentexception>` for errors related to the
+  parsing of parameters or options at the driver level.
+---
+ref: error-driver-runtimeexception
+content: |
+  :php:`MongoDB\\Driver\\Exception\\RuntimeException
+  <mongodb-driver-exception-runtimeexception>` for other errors at the driver
+  level (e.g. connection errors).
+---
+ref: error-badmethodcallexception-write-result
+content: |
+  :phpclass:`MongoDB\\Exception\\BadMethodCallException` if this method is
+  called and the write operation used an unacknowledged :manual:`write concern
+  </reference/write-concern>`.
+---
+ref: error-invalidargumentexception
+content: |
+  :phpclass:`MongoDB\\Exception\\InvalidArgumentException` for errors related to
+  the parsing of parameters or options.
+---
+ref: error-unexpectedvalueexception
+content: |
+  :phpclass:`MongoDB\\Exception\\UnexpectedValueException` if the command
+  response from the server was malformed.
+---
+ref: error-unsupportedexception
+content: |
+  :phpclass:`MongoDB\\Exception\\UnsupportedException` if options are used and
+  not supported by the selected server (e.g. ``collation``, ``writeConcern``).
+...

docs/index.txt

@@ -4,28 +4,25 @@ MongoDB PHP Library
 
 .. default-domain:: mongodb
 
-The |php-library| provides a high-level abstraction
-around the lower-level `PHP Driver <https://php.net/mongodb>`_, also
-known as the ``mongodb`` extension.
-
-While the ``mongodb`` extension provides a limited API for executing
-commands, queries, and write operations, the |php-library|
-implements an API similar to that of the `legacy PHP driver
-<http://php.net/manual/en/book.mongo.php>`_. The library contains
-abstractions for client, database, and collection objects, and provides
-methods for CRUD operations and common commands such as index and
+The |php-library| provides a high-level abstraction around the lower-level
+`PHP Driver <https://php.net/mongodb>`_, also known as the ``mongodb``
+extension.
+
+While the ``mongodb`` extension provides a limited API for executing commands,
+queries, and write operations, the |php-library| implements an API similar to
+that of the `legacy PHP driver <http://php.net/manual/en/book.mongo.php>`_. The
+library contains abstractions for client, database, and collection objects, and
+provides methods for CRUD operations and common commands such as index and
 collection management.
 
-If you are developing a PHP application with MongoDB, you should consider
-using this library, or another high-level abstraction, instead of the
-extension alone.
+If you are developing a PHP application with MongoDB, you should consider using
+this library, or another high-level abstraction, instead of the extension alone.
 
-For additional information about the MongoDB PHP Library and the
-``mongodb`` extension, see the `Architecture Overview
-<http://php.net/manual/en/mongodb.overview.php>`_ article in the
-extension documentation. `Derick Rethans <http://derickrethans.nl/>`_
-has also written a series of blog posts entitled *New MongoDB Drivers
-for PHP and HHVM*:
+For additional information about the MongoDB PHP Library and the ``mongodb``
+extension, see the `Architecture Overview
+<http://php.net/manual/en/mongodb.overview.php>`_ article in the extension
+documentation. `Derick Rethans <http://derickrethans.nl/>`_ has also written a
+series of blog posts entitled *New MongoDB Drivers for PHP and HHVM*:
 
 - `Part One: History <https://derickrethans.nl/new-drivers.html>`_
 
@@ -42,26 +39,23 @@ If you are a new MongoDB user, these links should help you become more familiar
 with MongoDB and introduce some of the concepts and terms you will encounter in
 this documentation:
 
-- `Introduction to CRUD operations in MongoDB
-  <http://docs.mongodb.org/manual/core/crud-introduction/>`_
+- :manual:`Introduction to CRUD operations in MongoDB </core/crud>`
 
-- `What is a MongoDB document?
-  <http://docs.mongodb.org/manual/core/document/>`_
+- :manual:`What is a MongoDB document? </core/document>`
 
-- `MongoDB's *dot notation* for accessing document properties
-  <http://docs.mongodb.org/manual/core/document/#dot-notation>`_
+- :manual:`Dot notation for accessing document properties
+  </core/document/#dot-notation>`
 
-- `ObjectId: MongoDB's document identifier
-  <http://docs.mongodb.org/manual/reference/object-id/>`_
+- :manual:`ObjectId: MongoDB's document identifier </reference/object-id/>`
 
 .. class:: hidden
 
    .. toctree::
       :titlesonly:
-      
+
       Installation </tutorial/install-php-library>
       /tutorial
       /upgrade
       /reference
 
-.. /getting-started
+.. /getting-started

docs/reference.txt

@@ -6,9 +6,12 @@ Reference
 
 .. toctree::
    :titlesonly:
-   
+
    /reference/bson
    /reference/class/MongoDBClient
    /reference/class/MongoDBDatabase
    /reference/class/MongoDBCollection
    /reference/class/MongoDBGridFSBucket
+   /reference/write-result-classes
+   /reference/enumeration-classes
+   /reference/exception-classes