MONGOID-5521 migrate Mongoid docs to snooty (#5513)

* fix code blocks

* MONGOID-5521 fix all parse errors

* build docs with github action

* Revert "build docs with github action"

This reverts commit 9ffda44.

Author: neilshweky

docs/reference/associations.txt

@@ -592,7 +592,7 @@ help of MongoDB projection operation:
   Band.where(started_on: {'$gt' => Time.now - 1.year}).only(:label).map(&:label).compact.uniq
 
 Setting Stale Values on Referenced Associations
-``````````````````````````````````````````````
+```````````````````````````````````````````````
 
 Setting a stale value to a referenced association can sometimes result in
 a ``nil`` value being persisted to the database. Take the following case:
@@ -744,14 +744,14 @@ The following deviations are known:
 
   As of this writing, the known cases of such deviation are:
 
-   - 3.2 and earlier servers not validating ``$size`` arguments as strictly as newer versions do.
-   - 4.0 and earlier servers not validating ``$type`` arguments as strictly as newer versions
-     do (allowing invalid arguments like 0, for example).
-   - 3.2 and earlier servers not supporting ``Decimal128`` for ``$type``, as well as allowing invalid
-     arguments such as negative numbers (smaller than -1) and numbers that are greater than 19
-     (not including 127, the argument for the ``MaxKey`` type).
-   - 3.4 and earlier servers not supporting arrays for ``$type``.
-   - 3.0 and earlier servers not supporting bitwise operators.
+  - 3.2 and earlier servers not validating ``$size`` arguments as strictly as newer versions do.
+  - 4.0 and earlier servers not validating ``$type`` arguments as strictly as newer versions
+    do (allowing invalid arguments like 0, for example).
+  - 3.2 and earlier servers not supporting ``Decimal128`` for ``$type``, as well as allowing invalid
+    arguments such as negative numbers (smaller than -1) and numbers that are greater than 19
+    (not including 127, the argument for the ``MaxKey`` type).
+  - 3.4 and earlier servers not supporting arrays for ``$type``.
+  - 3.0 and earlier servers not supporting bitwise operators.
 
 
 - Mongoid DSL expands ``Range`` arguments to hashes with ``$gte`` and ``$lte``

docs/reference/configuration.txt

@@ -656,7 +656,7 @@ use an initializer as follows:
   same instance as the Rails logger, modifying any of the instances affects
   all of them. For example the following changes log level for all three
   loggers, unless the application assigned a separate ``Logger`` instance
-  to `Mongo::Logger.logger`` as described above:
+  to ``Mongo::Logger.logger`` as described above:
 
   .. code-block:: ruby
 
@@ -839,7 +839,7 @@ Every ``Proc`` in ``Mongo.tls_context_hooks`` will be passed an
 ``OpenSSL::SSL::SSLContext`` object as its sole argument. These procs will
 be executed sequentially during socket creation.
 
-..warning ::
+.. warning::
 
   TLS context hooks are global and will affect all ``Mongo::Client`` instances
   in an application.
@@ -985,8 +985,8 @@ Query Cache Middleware
 .. note::
 
   When used with Ruby driver version 2.15 or newer, Mongoid's Query Cache
-  Middleware delegates to :ref:`the driver's Query Cache Middleware
-  <driver:query-cache-middleware>`.
+  Middleware delegates to `the driver's Query Cache Middleware
+  <https://www.mongodb.com/docs/ruby-driver/current/reference/query-cache/index.html#query-cache-middleware>`_.
 
 Mongoid provides a Rack middleware which enables the :ref:`Query Cache
 <query-cache>` for the duration of each web request. Below is an example of

docs/reference/fields.txt

@@ -21,7 +21,7 @@ Field Types
 MongoDB stores underlying document data using
 `BSON types <https://mongodb.com/docs/manual/reference/bson-types/>`_, and
 Mongoid converts BSON types to Ruby types at runtime in your application.
-For example, a field defined with `type: :float` will use the Ruby ``Float``
+For example, a field defined with ``type: :float`` will use the Ruby ``Float``
 class in-memory and will persist in the database as the the BSON ``double`` type.
 
 Field type definitions determine how Mongoid behaves when constructing queries
@@ -193,9 +193,9 @@ and has the same behavior in all circumstances.
 
 Mongoid also provides the deprecated ``Symbol`` field type for serializing
 Ruby symbols to BSON symbols. Because the BSON specification deprecated the
-BSON symbol type, the `bson` gem will serialize Ruby symbols into BSON strings
+BSON symbol type, the ``bson`` gem will serialize Ruby symbols into BSON strings
 when used on its own. However, in order to maintain backwards compatibility
-with older datasets, the `mongo` gem overrides this behavior to serialize Ruby
+with older datasets, the ``mongo`` gem overrides this behavior to serialize Ruby
 symbols as BSON symbols. This is necessary to be able to specify queries for
 documents which contain BSON symbols as fields.
 

docs/reference/queries.txt

@@ -233,7 +233,7 @@ and :ref:`field aliases <field-aliases>`:
   #   class:    Band
   #   embedded: false>
 
-Since `id` and `_id` fields are aliases, either one can be used for queries:
+Since ``id`` and ``_id`` fields are aliases, either one can be used for queries:
 
 .. code-block:: ruby
 
@@ -1713,43 +1713,43 @@ For example, consider the following model definition that contains a ``Time``
 field, a ``Date`` field and an implicit ``Object`` field, and also
 intentionally does not define a field called ``deregistered_at``:
 
-  .. code-block:: ruby
+.. code-block:: ruby
 
-    class Voter
-      include Mongoid::Document
+  class Voter
+    include Mongoid::Document
 
-      field :born_on, type: Date
-      field :registered_at, type: Time
-      field :voted_at
-    end
+    field :born_on, type: Date
+    field :registered_at, type: Time
+    field :voted_at
+  end
 
 Queries on ``born_on`` and ``registered_at`` fields using ``Date`` and ``Time``
 values, respectively, are straightforward:
 
-  .. code-block:: ruby
+.. code-block:: ruby
 
-    Voter.where(born_on: Date.today).selector
-    # => {"born_on"=>2020-12-18 00:00:00 UTC}
+  Voter.where(born_on: Date.today).selector
+  # => {"born_on"=>2020-12-18 00:00:00 UTC}
 
-    Voter.where(registered_at: Time.now).selector
-    # => {"registered_at"=>2020-12-19 04:33:36.939788067 UTC}
+  Voter.where(registered_at: Time.now).selector
+  # => {"registered_at"=>2020-12-19 04:33:36.939788067 UTC}
 
 But, note the differences in behavior when providing a ``Date`` instance
 in all possible scenarios:
 
-  .. code-block:: ruby
+.. code-block:: ruby
 
-    Voter.where(born_on: Date.today).selector
-    # => {"born_on"=>2020-12-18 00:00:00 UTC}
+  Voter.where(born_on: Date.today).selector
+  # => {"born_on"=>2020-12-18 00:00:00 UTC}
 
-    Voter.where(registered_at: Date.today).selector
-    # => {"registered_at"=>2020-12-18 00:00:00 -0500}
+  Voter.where(registered_at: Date.today).selector
+  # => {"registered_at"=>2020-12-18 00:00:00 -0500}
 
-    Voter.where(voted_at: Date.today).selector
-    # => {"voted_at"=>Fri, 18 Dec 2020}
+  Voter.where(voted_at: Date.today).selector
+  # => {"voted_at"=>Fri, 18 Dec 2020}
 
-    Voter.where(deregistered_at: Date.today).selector
-    # => {"deregistered_at"=>2020-12-18 00:00:00 UTC}
+  Voter.where(deregistered_at: Date.today).selector
+  # => {"deregistered_at"=>2020-12-18 00:00:00 UTC}
 
 When using the ``registered_at`` field which is of type ``Time``, the date
 was interpreted to be in local time (as per the :ref:`configured time zone
@@ -2467,7 +2467,7 @@ on when the query results are being accessed:
   Even though ``load_async`` method returns a ``Criteria`` object, you should not
   do any operations on this object except accessing query results. The query is
   scheduled for execution immediately after calling ``load_async``, therefore
-  later changes to the `Criteria`` object may not be applied.
+  later changes to the ``Criteria`` object may not be applied.
 
 
 Configuring asynchronous query execution

docs/reference/rails-integration.txt

@@ -61,7 +61,7 @@ Controller Runtime Instrumentation
 
 Mongoid provides time spent executing MongoDB commands (obtained via a
 driver command monitoring subscription) to Rails' instrumentation event
-`process_action.action_controller`. This time is logged together with view
+``process_action.action_controller``. This time is logged together with view
 time like so:
 
 .. code-block:: none

docs/release-notes/mongoid-7.2.txt

@@ -260,7 +260,7 @@ instead of loading the entire association.
 ``StringifiedSymbol`` Field Type
 --------------------------------
 
-New feature: the :ref:`StringifiedSymbol field type <stringified-symbol>`
+New feature: the :ref:`StringifiedSymbol field type <field-type-stringified-symbol>`
 was added for storing Ruby symbol values in MongoDB in a manner interoperable
 with other programming languages.
 
@@ -414,7 +414,7 @@ of the legacy query cache, see :ref:`the query cache documentation <query-cache>
 Minor change: when a ``String`` value is written in a ``Regexp`` field,
 Mongoid 7.2 stores that value in MongoDB as a regular expression.
 Subsequently it would be retrieved :ref:`as a BSON::Regexp::Raw instance
-<regular-expression-fields>`.
+<field-type-regexp>`.
 Previously the value would be stored as a string and would be retrieved as
 a string.
 

docs/release-notes/mongoid-8.0.txt

@@ -152,21 +152,21 @@ Changes to the ``attributes_before_type_cast`` Hash
 The ``attributes_before_type_cast`` hash has been changed to function more like
 ActiveRecord:
 
-  - On instantiation of a new model (without parameters), the
-    ``attributes_before_type_cast`` hash has the same contents as the
-    ``attributes`` hash. If parameters are passed to the initializer, those
-    values will be stored in the ``attributes_before_type_cast`` hash before
-    they are ``mongoized``.
-  - When assigning a value to the model, the ``mongoized`` value (i.e. when
-    assiging '1' to an Integer field, it is ``mongoized`` to 1) is stored in
-    the ``attributes`` hash, whereas the raw value (i.e. '1') is stored in the
-    ``attributes_before_type_cast`` hash.
-  - When saving, creating (i.e. using the ``create!`` method), or reloading the
-    model, the ``attributes_before_type_cast`` hash is reset to have the same
-    contents as the ``attributes`` hash.
-  - When reading a document from the database, the ``attributes_before_type_cast``
-    hash contains the attributes as they appear in the database, as opposed to
-    their ``demongoized`` form.
+- On instantiation of a new model (without parameters), the
+  ``attributes_before_type_cast`` hash has the same contents as the
+  ``attributes`` hash. If parameters are passed to the initializer, those
+  values will be stored in the ``attributes_before_type_cast`` hash before
+  they are ``mongoized``.
+- When assigning a value to the model, the ``mongoized`` value (i.e. when
+  assiging '1' to an Integer field, it is ``mongoized`` to 1) is stored in
+  the ``attributes`` hash, whereas the raw value (i.e. '1') is stored in the
+  ``attributes_before_type_cast`` hash.
+- When saving, creating (i.e. using the ``create!`` method), or reloading the
+  model, the ``attributes_before_type_cast`` hash is reset to have the same
+  contents as the ``attributes`` hash.
+- When reading a document from the database, the ``attributes_before_type_cast``
+  hash contains the attributes as they appear in the database, as opposed to
+  their ``demongoized`` form.
 
 
 Order of Callback Invocation

docs/tutorials/getting-started-rails6.txt

@@ -105,7 +105,6 @@ Add Mongoid
 `mongoid <https://rubygems.org/gems/mongoid/>`_ gem:
 
 .. code-block:: ruby
-  :name: Gemfile
   :caption: Gemfile
 
     gem 'mongoid', '~> 7.0.5'
@@ -132,6 +131,8 @@ Note that as we are not using ActiveRecord we will not have a ``database.yml``
 file.
 
 
+.. _run-locally:
+
 Run MongoDB Locally
 -------------------
 
@@ -157,6 +158,8 @@ like this:
             server_selection_timeout: 1
 
 
+.. _use-atlas:
+
 Use MongoDB Atlas
 -----------------
 
@@ -247,7 +250,6 @@ Open the ``Post`` model file, ``app/models/post.rb``, and add a ``has_many``
 association for the comments:
 
 .. code-block:: ruby
-  :name: app/models/post.rb
   :caption: app/models/post.rb
 
     class Post
@@ -267,7 +269,6 @@ association for the comments:
   generated ``embedded_in`` association to ``belongs_to``:
 
   .. code-block:: ruby
-    :name: app/models/comment.rb
     :caption: app/models/comment.rb
 
       class Comment
@@ -283,7 +284,6 @@ Open the post show view file, ``app/views/posts/show.html.erb``, and add
 a section rendering existing comments and prompting to leave a new comment:
 
 .. code-block:: html
-  :name: app/views/posts/show.html.erb
   :caption: app/views/posts/show.html.erb
 
   <section class="section comments">
@@ -306,7 +306,6 @@ from ``text_field`` to ``text_area``, as well as the type of field for
 should look like this:
 
 .. code-block:: html
-  :name: app/views/comments/_form.html.erb
   :caption: app/views/comments/_form.html.erb
 
   <%= form_with(model: comment, local: true) do |form| %>
@@ -345,7 +344,6 @@ Create a partial for the comment view, ``app/views/comments/_comment.html.erb``
 with the following contents:
 
 .. code-block:: html
-  :name: app/views/comments/_comment.html.erb
   :caption: app/views/comments/_comment.html.erb
 
   <p>
@@ -377,7 +375,6 @@ Remove or comment out any RDBMS libraries like ``sqlite``, ``pg`` etc.
 mentioned in ``Gemfile``, and add ``mongoid``:
 
 .. code-block:: ruby
-  :name: Gemfile
   :caption: Gemfile
 
     gem 'mongoid', '~> 7.0.5'
@@ -399,7 +396,6 @@ Examine ``config/application.rb``. If it is requiring all components of Rails
 via ``require 'rails/all'``, change it to require individual frameworks:
 
 .. code-block:: ruby
-  :name: config/application.rb
   :caption: config/application.rb
 
   # Remove or comment out
@@ -472,9 +468,9 @@ Generate the default Mongoid configuration:
 This generator will create the ``config/mongoid.yml`` configuration file,
 which is used to configure the connection to the MongoDB deployment.
 
-Review the sections `Run MongoDB Locally`_ and `Use MongoDB Atlas`_
-to decide how you would like to deploy MongoDB, and adjust Mongoid
-configuration (``config/mongoid.yml``) to match.
+Review the sections :ref:`Run MongoDB Locally <run-locally>` and
+:ref:`Use MongoDB Atlas <use-atlas>` to decide how you would like to deploy
+MongoDB, and adjust Mongoid configuration (``config/mongoid.yml``) to match.
 
 Adjust Models
 -------------
@@ -491,7 +487,6 @@ explicit field definitions).
 For example, a bare-bones Post model may look like this in ActiveRecord:
 
 .. code-block:: ruby
-  :name: app/models/post.rb
   :caption: app/models/post.rb
 
   class Post < ApplicationRecord
@@ -501,7 +496,6 @@ For example, a bare-bones Post model may look like this in ActiveRecord:
 The same model may look like this in Mongoid:
 
 .. code-block:: ruby
-  :name: app/models/post.rb
   :caption: app/models/post.rb
 
   class Post
@@ -516,7 +510,6 @@ The same model may look like this in Mongoid:
 Or like this with dynamic fields:
 
 .. code-block:: ruby
-  :name: app/models/post.rb
   :caption: app/models/post.rb
 
   class Post
@@ -555,5 +548,5 @@ as when creating a regular application, with the only change being the
 Mongoid follows the same process described above for regular Rails applications.
 
 A complete Rails API application similar to the one described in this tutorial
-can be found in the `mongoid-demo GitHub repository
+can be found in `the mongoid-demo GitHub repository
 <https://github.com/mongoid/mongoid-demo/tree/master/rails-api>`_.